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Preface 


This publication describes features of TSO 
that can be replaced, modified, or added to 
by each installation of TSO, to adapt the 
command system to the installation's 
particular needs. The manual is intended 
for programmers whose responsibility is to 
modify the portions of TSO that communicate 
directly with the user at the terminal. 


The publication discusses the Terminal 
Monitor Program and the Command Processors 
from the viewpoint of their replaceability, 
and describes the programming features 
provided within TSO for user-written 
terminal monitor programs, command 
processors, and applications programs. 
These features includes 


Service Routines 

Macro Instructions 

SVCs 

The Dynamic Allocation Interface Routine 

(DAIR) 

The TEST Command Processor 

This publication contains information 
required by a programmer writing a terminal 
monitor program or a command processor for 
the Time Sharing Option. It discusses the 
functions that a Terminal Monitor Program 
or a command processor should provide, and 
it describes the macro instructions and 
service routines that can be used to 
provide these functions. 

The book is divided into twelve 
sections : 

• Introduction 

• Terminal Monitor Program 

• Command Processors 

• Message Handling 

• Attention Interruption Handling -- The 
STAX Service Routine 

• Dynamic Allocation of Data Sets — The 
Dynamic Allocation Interface Routine 

(DAIR) 

• Using BSAM or QSAM for Terminal I/O 

• Using the TSO I/O Service Routines for 
Termina1 I/O 

• Using the TGET/TPUT SVC for Terminal 
I/O 


• Using Terminal Control Macro 
Instructions 

• Command Scan and Parse — Determining 
the Validity of Commands 

• Testing a Newly Written Program — The 
TEST Command 

The first four sections describe the 
functions performed by a terminal monitor 
program or a command processor, and explain 
message processing conventions peculiar to 
the Time Sharing Option. 

The next seven sections describe the 
macro instructions and service routines 
that a programmer can use to provide the 
required functions. These macro 
instructions and service routines can be 
used to schedule and process attention 
interruptions, to allocate, free, 
concatenate, and deconcatenate data sets 
during program execution, to provide I/O 
between a program and a terminal, to 
control terminal functions and attributes, 
and to determine the validity of commands, 
subcommands, and operands entering the 
system. 

The last section describes the TEST 
command and how it can be used to test a 
newly written program at the terminal. 

Prerequisite and Reference Publications 

The reader of this publication should 
have a knowledge of the structure of the 
Time Sharing Option, as described in IBM 
System/360 Operating System: Time sharing 
Option Guide , GC28-6698. 

In addition, the reader should have the 
following publications available for 
reference: 

IBM System/360 Principles of Operation , 
GA22-6 821. 

IBM System/360 Operating System : 

Data Management for System Programmers , 

GC 28-6 550 (formerly System Programmer's 

Guide) . 

Data Management Macro Instructions , 

GC26-3794• 

Data Management Services , GC26-3746. 

Job Control Language Reference , 

GC2 8-67 04. 
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Supervisor Services and Macro 
Instructions ,, GC28-6646. 

System Control Blocks , GC28-6628 

Storage Estimates , GC28-6551. 

Time Sharing Option : 

Command Language Reference , 
GC28-6732. 


Command Processor Program Logic 
Manual , GY28-6771 through GY28-6776. 


Control Program, Program Logic 
Manual, GY27-7199. 

Terminal Monitor Program and Service 
Routines. Program Logic Manual . 
GY28-6770. 

Terminal User's Guide, GC28-6763. 


4 Guide to Writing a TMP or a CP (Release 21.6) 



Contents 


SUMMARY OF AMENDMENTS FOR GC28-6764-2 
OS RELEASE 21.6.11 

SUMMARY OF AMENDMENTS FOR GC28-6764-1 

AS UPDATED BY GN28-2523 COMPONENT 

RELEASE 360S-OS-586 . .. 12 

SUMMARY OF AMENDMENTS FOR GC28-6764-1 
OS RELEASE 21.13 

SUMMARY OF AMENDMENTS FOR GC28-6764-0 
AS UPDATED BY GN28-2484 OS RELEASE 20.1 15 

INTRODUCTION . 17 

The Terminal Monitor Program (TMP) 

and Command Processors . 17 

Basic Functions of Terminal Monitor 
Programs and Command Processors ... 18 
Communicating with the User at the 

Terminal.18 

Passing Control to Commands and 

Subcommands.19 

Responding to Abnormal Terminations 19 
Responding to Attention 

Interruptions . 19 

Other Functions Provided with TSO . . 20 
The Dynamic Allocation of Data Sets 20 
Testing a Terminal Monitor Program 

or a Command Processor.20 

Summary ..21 

THE TERMINAL MONITOR PROGRAM . 22 

Specifying Data Sets at LOGON.22 

Terminal Monitor Program Initialization 23 

Requesting A Command . 23 

Intercepting An ABEND . 25 

Intercepting a Subtask ABEND . 25 

Intercepting a TMP TASK ABEND .... 29 
Processing An Attention Interruption . .30 
Parameters Received by Attention 

Handling Routines . 30 

The Attention Exit Parameter List . 32 
The Terminal Attention Interrupt 

Element (TAIE).32 

Processing a STOP Command ....... 33 

COMMAND PROCESSORS . 34 

Response Time.35 

Program Design . ....... 35 

Module Size and Storage Requirements . 37 
Command Processor Use of the TSO 

Service Routines . 37 

STACK Service Routine ..37 

GETLINE Service Routine.38 

PUTLINE Service Routine . 38 

PUTGET Service Routine . 38 

DAIR Service Routine . ..38 

Command Scan Service Routine.38 

PARSE Service Routine.39 

STAE/STAI Exit Routines - Intercepting 

an ABEND.. . ..39 

Attention Exit Routines . ..40 


Adding Commands to the Time Sharing 

Option.41 

The HELP Data Set.41 

Private HELP Data Sets.42 

Formatting the HELP Data Set.42 

MESSAGE HANDLING . 45 

Message Levels . 45 

Effects of the Input Source on Message 
Processing.46 

ATTENTION INTERRUPTION HANDLING - THE 

STAX SERVICE ROUTINE.47 

Specifying a Terminal Attention Exit - 

The STAX Macro Instruction.47 

The STAX Parameter List ..51 

Coding Example of the STAX Macro 

Instruction.52 

Return Codes From the STAX Service 
Routine. 53 

DYNAMIC ALLOCATION OF DATA SETS — THE 
DYNAMIC ALLOCATION INTERFACE ROUTINE 

(DAIR).54 

Using DAIR.55 

The DAIR Parameter List (DAPL) .... 56 
The DAIR Parameter Block (DAPB) ... 57 
Code X 1 00' - Search the DSE for a 

Data Set Name.58 

Code X' 04 1 - Search the DSE and 
the System Catalog for Data Set 

Name .. 59 

Code X 1 08 * - Allocate a Data Set 

by DSNAME. 60 

Code X * 0C • - Concatenate the 

Specified DDNAMES . 63 

Code X'10• - Deconcatenate the 

Indicated DDNAME . 64 

Code X 1 14 1 - Return Qualifiers for 

the Specified DSNAME.65 

Code X*18 1 - Free the Specified 

Data set.66 

Code X'lC' - Allocate the 

Specified DDNAME to the Terminal . . 68 

Code X* 24• - Allocate a Data Set 

by DDNAME.69 

Code X 1 28 1 - Perform a List of 

DAIR Operations. ..72 

Code X• 2C• - Mark Data Sets as Not 

in Use.73 

Code X'30 f - Allocate a SYSOUT 

Data Set.74 

Code X*34' - Build or Delete an 
Attribute Control Block (ATRCB) . . 76 
DAIRACB - DAIR Attribute Control 

Block.77 

Return Codes from DAIR.79 

Return Codes from Dynamic Allocation . . 80 

USING BSAM OR QSAM FOR TERMINAL I/O . . 85 

BSAM/QSAM Macro Instructions . 86 

SAM Terminal Routines . 87 


Contents 5 































































GET . . .. 87 

PUT and PUTX ...... . 88 

READ. 88 

WRITE ............... 88 

CHECK. 88 

Record Formats, Buffering Techniques, 

and Processing Modes.. . 89 

Specifying Terminal Line Size ..... 89 
End of File (EOF) for Input Processing . 89 
Modifying DD Statements for Batch or 
TSO Processing .. ...89 

USING THE TSO I/O SERVICE ROUTINES FOR 
TERMINAL I/O . . . ..90 


Interface with the I/O Service Routines 91 
The Command Processor Parameter List . 92 


The Input Output Parameter List ... 92 
Passing Control to the I/O Service 

Routines. 95 

The I/O Service Routine Macro 

Instructions. 95 

STACK - Changing The Source of Input . 96 
The STACK Macro Instruction - List 

Form ..96 

The STACK Macro Instruction - 

Execute Form .. 98 

Sources of Input .100 

Building the STACK Parameter Block .101 
Building the List Source 

Descriptor (LSD) . . ..105 

Return Codes From STACK ..... .110 
GETLINE - Getting a Line of Input . .110 
The GETLINE Macro Instruction - 

List Form. Ill 

The GETLINE Macro Instruction - 

Execute Form ... . . .113 

Sources of Input ......... .116 

End of Data Processing ...... .116 

Building the GETLINE Parameter 

Block . ..116 

Input Line Format - The Input 

Buffer ... . .118 

Examples of GETLINE.119 

Return Codes from GETLINE .122 

PUTLINE - Putting a Line Out to the 

Terminal . ..122 

The PUTLINE Macro Instruction - 

List Form.123 

The PUTLINE Macro Instruction - 

Execute Form ..126 

Building the PUTLINE Parameter 

Block ..131 

Types and Formats of Output Lines .133 

PUTLINE Message Line Processing: . .141 

Return Codes From PUTLINE .... .149 

PUTGET - Putting a Message Out to 
the Terminal and Obtaining a Line of 

Input in Response.149 

The PUTGET Macro Instruction - 

List Form.150 

The PUTGET Macro Instruction - 

Execute Form.154 

Building the PUTGET Parameter 

Block (PGPB) . ..160 

Types and Formats of the Output 

Line.162 

Passing the Message Lines to PUTGET 162 

PUTGET Processing.165 


Input Line Format - the Input 

Buffer.. ..166 

An Example of PUTGET. .168 

Return Codes From PUTGET ..... .172 

USING THE TGET/TPUT SVC FOR TERMINAL 

I/O . .. 173 

The TPUT Macro Instruction - Writing a 

Line to the Terminal.174 

Return Codes From TPUT ..177 

The TGET Macro Instruction — Getting 

a Line From the Terminal.178 

Return Codes from TGET.18 0 

Formatting the TGET/TPUT Parameter 

Registers.181 

Coding Examples Of TGET And TPUT Macro 

Ins tructions.182 

Examples of Both TPUT and TGET Using 

the Default Values.182 

Example of TPUT Macro Instruction — 
Buffer Address and Buffer Length in 

Registers. . . ..183 

Example of the TGET Macro 

Instruction — Register Format . . . .184 

USING TERMINAL CONTROL MACRO 

INSTRUCTIONS.185 


GTSIZE — Get Terminal Line Size . .185 
RTAUTOPT — Restart Automatic Line 
Numbering or Character Prompting . .186 
SPAUTOPT — Stop Automatic Line 
Numbering or Character Prompting . .187 
STATTN — Set Attention Simulation .188 


STATUS — Change Subtask Status . .189 
STAUTOCP — Start Automatic 

Character Prompting ..19 0 

STAUTOLN — Start Automatic Line 

Numbering.191 

STBREAK — Set Break.192 

STCC — Specify Terminal Control 

Characters .193 

STCLEAR — Set Display Clear 

Character String.19 5 

STCOM — Set Inter-Terminal 

Communication.196 

STSIZE — Set Terminal Line Size . .196 
STTIMEOU — Set Timeout Feature . .198 
TCLEARQ — Clear Buffers .199 

COMMAND SCAN AND PARSE - DETERMINING 

THE VALIDITY OF COMMANDS.201 

Sequence of Operations.201 

Using The Command Scan Service Routine 

(IKJSCAN) . ..202 

Command Name Syntax.202 

The Parameter List Structure 

Required by Command Scan.203 


The Command Scan Parameter List . .204 
Flags Passed to Command Scan . . . .204 
The Command Scan Output Area . . . .204 
The Operation of The Command Scan 


Service Routine.205 

Results of the Command Scan.207 

Return Codes from Command Scan . . . .207 
Using the Parse Service Routine 

(IKJPARS ).208 

Command Parameter Syntax.211 

Positional Parameters.211 


6 Guide to Writing a TMP or a CP (Release 21.6) 




































































Keyword Parameters.221 

Using the Parse Macro Instructions 

to Define Command Syntax ..222 

IKJPARM - Beginning the PCL and 

the PDL.223 

IKJPOSIT - Describing a 
Delimiter-Dependent Positional 

Parameter.224 

IKJTERM - Describing a 
Delimiter-Dependent Positional 

Parameter ..228 

IKJOPER - Describing a 
Delimiter-Dependent Positional 

Parameter.232 

IKJRSVWD - Describing a 
Delimiter-Dependent Positional 

Parameter.236 

IKJIDENT - Describing a 
Non-Delimiter Dependent Positional 

Parameter.239 

IKJKEYWD - Describing a Keyword 

Parameter.244 

IKJNAME - Listing the Keyword or 
Reserved Word Parameter Names . . .245 
IKJSUBF - Describing a Keyword 

Subfield.248 

IKJENDP - Ending the Parameter 

Control List.249 

IKJRLSA - Releasing Storage 

Allocated by Parse.249 

Passing Control to the Parse Service 

Routine ..250 

The Parse Parameter List.251 

Formats of the PDEs Returned by Parse 252 

The PDL Header.252 

PDEs Created for Positional 

Parameters. .252 

Affect of List and Range Options 

on PDE Formats ..263 

The PDE Created for a Keyword 
Parameter ..270 


Additional Facilities Provided by 

Parse ..270 

Translation to Upper Case.27 0 

Insertion of Default Values . . . .270 
Passing Control to a Validity 

Checking Routine.271 

Insertion of Keywords.27 2 

Issuing Second Level Messages . . .272 

Prompting. 273 

Examples of Using the PARSE Service 

Routine.275 

Return Codes from the Parse Service 
Routine.288 

TESTING A NEWLY WRITTEN PROGRAM — THE 

TEST COMMAND.290 

When You Would Use TEST.292 

Addressing Restrictions.293 

Executing a Program Under the 

Control of TEST.293 

Establishing and Removing 

Breakpoints Within a Programs . . . .295 
Displaying selected Areas of storage .295 
Changing Instructions, Data Areas, 

or Register Contents.297 

Forcing Execution of Program 
Subroutines. 297 


Using TEST After a Program ABEND . . .298 
Determining Data Set Information . .298 

APPENDIX As TSO CONTROL BLOCKS . . . -299 


Environment Control Table.300 

Protected Step Control Block . . ... .301 

Time-Sharing Job Block.303 

User Profile Table.306 

APPENDIX Bs NOTATION FOR DEFINING 

MACRO INSTRUCTIONS.307 

GLOSSARY . ..309 


Contents 7 








































Figures 


Figure 1. A LOGON Procedure 
Containing Four DD DYNAM Entries ... 22 
Figure 2. Requesting a Command .... 24 
Figure 3. The TSEVENT Macro 

Instruction Specifying PPMODE . 25 

Figure 4. ABEND f STAE, STAI 

Relationship . .. 26 

Figure 5. The Test Parameter List 

(Part 1 of 3). 27 

Figure 6. Parameters Passed to the 

Attention Exit Routine . 31 

Figure 7. The Attention Exit 

Parameter List .32 

Figure 8. The Terminal Attention 

Interrupt Element ..32 

Figure 9. storage Map - MVT with 

Time Sharing Option.36 

Figure 10. Cards Used to Format a 

HELP Data Set.43 

Figure 11. Coding Example — 

Including the SAMPLE Command in the 

HELP Data Set.44 

Figure 12. The STAX Macro Instruction 

— List and Execute Forms.48 

Figure 13. Using Registers in the 

STAX Macro Instruction . 50 

Figure 14. The STAX Parameter List . . 51 
Figure 15. Coding Example — STAX 

Macro Instruction.52 

Figure 16. Control Blocks Passed to 

DAIR ..55 

Figure 17. Format of the DAIR 

Parameter List (DAPL) ..56 

Figure 18. DAIR Entry Codes and Their 

Functions .. .....57 

Figure 19. DAIR Parameter Block — 

Entry Code X'00* . 58 

Figure 20. DAIR Parameter Block — 

Entry Code X'04' . 59 

Figure 21. DAIR Parameter Block — 

Entry Code X'08 1 (Part 1 of 3) .... 60 

Figure 22. DAIR Parameter Block — 

Entry Code X'OC .63 

Figure 23. DAIR Parameter Block — 

Entry Code X'10* .64 

Figure 24. DAIR Parameter Block — 

Entry Code X'14* .65 

Figure 25. DAIR Parameter Block — 

Entry Code X*18' (Part 1 of 2) .... 66 

Figure 26. DAIR Parameter Block — 

Entry Code X'lC* . 68 

Figure 27. DAIR Parameter Block — 

Entry Code X'24' (Part 1 of 3) .... 69 

Figure 28. DAIR Parameter Block — 

Entry Code X" 28'. 72 

Figure 29. DAIR Parameter Block — 

Entry Code X , 002C* .73 

Figure 30. DAIR Parameter Block — 

Entry Code X'30* (Part 1 of 2) .... 74 

Figure 31. DAIR Parameter Block — 

Entry Code X'34 f 76 


Figure 32. DAIR Attribute Control 

Block (DAIRACB) (Part 1 of 2).77 

Figure 33. BSAM/QSAM Function under 

TSO (Part 1 of 2).86 

Figure 34. Control Block Interface 

Between TMP and CP . ..91 

Figure 35. The Command Processor 
Parameter List (CPPL) 

. . 92 

Figure 36. The Input Output Parameter 

List ..93 

Figure 37. Control Block Interface 
Between TMP and I/O Service Routine . . 94 
Figure 38. The List Form of the STACK 

Macro Instruction.96 

Figure 39. The Execute form of the 

STACK Macro Instruction ..98 

Figure 40. The STACK Parameter Block 

..102 

Figure 41. STACK Control Blocks: No 

In-Storage List.. . .103 

Figure 42. Coding Example — STACK 
Specifying the Terminal as the Input 

Source . .104 

Figure 43. The List Source Descriptor 105 

Figure 44. STACK Control Blocks: 

In-Storage List Specified .106 

Figure 45. Coding Example — STACK 
Specifying an In-Storage List as the 
Input Source (Part 1 of 3) ..... .107 

Figure 46. The List Form of the 

GETLINE Macro Instruction . . .111 

Figure 47. The Execute Form of the 

GETLINE Macro Instruction .113 

Figure 48. The GETLINE Parameter 

Block. 117 

Figure 49. Format of the GETLINE 

Input Buffer . 118 

Figure 50. GETLINE Control Blocks - 

Input Line Returned.119 

Figure 51. Coding Example — Two 
Executions of GETLINE (Part 1 of 2) . .120 

Figure 52. The List Form of the 

PUTLINE Macro Instruction .123 

Figure 53. The Execute Form of the 

PUTLINE Macro Instruction .127 

Figure 54. The PUTLINE Parameter 

Block (Part 1 of 2).132 

Figure 55. PUTLINE Single Line Data 

Format . 134 

Figure 56. Coding Example — PUTLINE 

Single Line Data . .135 

Figure 57. PUTLINE Multi-Line Data 

Format .136 

Figure 58. Coding Example — PUTLINE 

Multi-Line Data (Part 1 of 2).137 

Figure 59. The Output Line Descriptor 139 

Figure 60. Control Block Structures 

for PUTLINE Messages .140 

Figure 61. PUTLINE Functions and 

Message Types .141 


8 Guide to Writing a TMP or a CP (Release 21.6) 




















































Figure 62. Coding Example — PUTLINE 

Text Insertion (Part 1 of 2) 144 

Figure 63. Coding Example — PUTLINE 
Second Level Informational Chaining 

(Part 1 of 2).147 

Figure 64. The List Form of the 

PUTGET Macro Instruction .150 

Figure 65. The Execute Form of the 

PUTGET Macro Instruction .155 

Figure 66. The PUTGET Parameter Block 

(Part 1 of 2).160 

Figure 67. The Output Line Descriptor 

(OLD) . . . ..163 

Figure 68. Control Block Structures 

for PUTGET Output Messages .164 

Figure 69. Format of the PUTGET Input 

Buffer .167 

Figure 70. PUTGET Control Block 


Structure - Input Line Returned . . . .168 

Figure 71. Coding Example -- PUTGET 
Multi-Level PROMPT Message (Part 1 of 

3) . . ..169 

Figure 72. The TPUT Macro Instruction 

— Standard and Register Forms . . . .174 

Figure 73. The TGET Macro Instruction 

— Standard and Register Forms . . . .178 

Figure 74. TGET/TPUT Parameter 


Registers.181 

Figure 75. Coding Example — of TPUT 
and TGET Macro Instructions Using the 

Default Values . 182 

Figure 76. Coding Example: TPUT Macro 
Instruction Buffer Address and Buffer 

Length in Registers .183 

Figure 77. Coding Example: TGET Macro 

Instruction Register Format .184 

Figure 78. The GTSIZE Macro 

Instruction.186 

Figure 79. The RTAUTOPT Macro 

Instruction.186 

Figure 80. The SPAUTOPT Macro 

Instruction ..187 

Figure 81. The STATTN Macro 

Instruction.188 

Figure 82. The STATUS Macro 

Instruction . ...189 

Figure 83. The STAUTOCP Macro 

Instruction.191 

Figure 84. The STAUTOLN Macro 

Instruction.192 

Figure 85. The STBREAK Macro 

Instruction.193 

Figure 86. The STCC Macro Instruction 194 
Figure 87. The STCLEAR Macro 

Instruction ...195 

Figure 88. The STCOM Macro 

Instruction.196 

Figure 89. The STSIZE Macro 

Instruction . ....197 

Figure 90. The STTIMEOU Macro 

Instruction ..199 

Figure 91. The TCLEARQ Macro 

Instruction ...2 00 

Figure 92. The Parameter List 
Structure Passed to Command Scan . . .203 

Figure 93. The Command Scan Parameter 
List .2 04 


Figure 94. The Command Scan Output 

Area .205 

Figure 95. Character Types Recognized 

by Command Scan and Parse.206 

Figure 96. Return from Command Scan - 
CSOA and Command Buffer Settings . . .207 
Figure 97. A Command Processor Using 
the Parse Service Routine . .209 

I Figure 98. Delimiter-Dependent 

Parameters . 212 

Figure 99. The IKJPARM Macro 

Instruction.223 

Figure 100. The Parameter Control 

Entry Built by IKJPARM.223 

Figure 101. The IKJPOSIT Macro 

Instruction.224 

Figure 102. The Parameter Control 

Entry Built by IKJPOSIT (Part 1 of 2) .226 

Figure 103. The IKJTERM Macro 

Instruction.228 

Figure 104. The Parameter Control 

Entry Built by IKJTERM (Part 1 of 2) . .230 

Figure 105. The IKJOPER Macro 

Instruction ..232 

Figure 106. The Parameter Control 

Entry Built by IKJOPER (Part 1 of 2) . .234 

Figure 107. The IKJRSVWD Macro 

Instruction.236 

Figure 108. The Parameter Control 

Entry Built by IKJRSVWD (Part 1 of 2) .237 

Figure 109- The IKJIDENT Macro 

Instruction.239 

Figure 110. The Parameter Control 

Entry Built by IKJIDENT (Part 1 of 3) .241 

Figure 111. The IKJKEYWD Macro 

Instruction.244 

Figure 112. The Parameter Control 
Entry Built by IKJKEYWD (Part 1 of 2) .244 

Figure 113. The IKJNAME Macro 
Instruction (When used with the 

IKJKEYWD Macro Instruction).245 

Figure 114. The IKJNAME Macro 
Instruction (when used with the 

IKJRSVWD macro) . . . ..246 

Figure 115. The Parameter Control 

Entry Built by IKJNAME ..247 

Figure 116. The IKJSUBF Macro 

Instruction ..248 

Figure 117. The Parameter Control 

Entry Built by IKJSUBF .24 8 

Figure 118. The IKJENDP Macro 

Instruction.249 

Figure 119. The Parameter Control 

Entry Built by IKJENDP .. . .249 

Figure 120. The IKJRLSA Macro 

Instruction.24 9 

Figure 121. Control Flow Between 

Command Processor and Parse.250 

Figure 122. The Parse Parameter List .251 

Figure 123. A PDL Showing PDEs 

Describing a List.264 

Figure 124. A PDL Showing PDEs 

Describing a Range .265 

Figure 125. PDL Showing PDEs 
Describing LIST and RANGE Options . . .266 

Figure 126. PDL - LIST and RANGE 
Acceptable, Single Parameter Entered .267 


Figures 9 





















































Figure 127. PDL - LIST and RANGE 
Acceptable,, Single Range Entered . . .267 
Figure 128. PDL - LIST and RANGE 

Acceptable, LIST Entered ..268 

Figure 129. PDL - LIST and RANGE 
Acceptable, A LIST of Ranges Entered .269 
Figure 130. Format of the Validity 

Check Parameter List ..271 

Figure 131. Return Codes from a 

Validity Checking Routine ..272 

Figure 132. Coding Example 1 — Using 
Parse Macros to Describe Command 
Parameter Syntax . . . .276 

Figure 133. An IKJPARMD DSECT 

(Example 1) 277 

Figure 134. The IKJPARMD DSECT and 

the PDL (Example 1) ........ . .278 

Figure 135. Coding Example 2 — Using 
Parse Macros to Describe Parameter 
Syntax ................279 

Figure 136. An IKJPARMD DSECT 

(Example 2) ... . .280 


Figure 137. The IKJPARMD DSECT and 

the PDL (Example 2) ........ .282 

Figure 138. Coding Example 3 — Using 
Parse Macros to Describe Parameter 

Syntax ........ .283 

Figure 139. An IKJPARMD DSECT 

(Example 3).284 

Figure 140. The IKJPARMD DSECT and 

the PDL (Example 3) . . ..285 

Figure 141. Coding Example 4 — Using 
Parse Macros to Describe Parameter 

Syntax .286 

Figure 142. An IKJPARMD DSECT 

(Example 4) .287 

Figure 143. The IKJPARMD DSECT and 

the PDL (Example 4) . ..288 

Figure 144. The TEST Subcommands . . .291 
Figure 145. Issuing the TEST Command .294 

Figure 146. Environment Control Table .300 


Figure 147. Protected Step Control 

Block (Part 1 of 2).301 

Figure 148. Time-Sharing Job Block 

(Part 1 of 3) ..303 


Figure 149. User Profile Table . . . .306 


10 Guide to Writing a TMP or a CP (Release 21.6) 




















Summary of Amendments 
for GC28-6764-2 
OS Release 21.6 


DAIRACB - PAIR Attribute Control Block 
A correction is made to Figure 30,2. 


USING THE PARSE SERVICE ROUTINE (IKJPARS) 

The following three macro instructions 
are added to the Parse Service Routine. 

• IKJTERM I RETURN CODES FROM THE PARSE SERVICE ROUTINE 

• IKJOPER I Return code 24 (decimal) is added to 

• IKJRSVWD I the Parse routine. 

These macro instructions provide syntax 
checking for the following positional 
parameter types. 

• CONSTANT 

• VARIABLE 

• STATEMENT NUMBER 

• EXPRESSION 

• RESERVED WORD 

Information is provided in the section 
entitled "Using the Parse Service 
Routine" (IKJPARS) 


IKJNAME - Listing the Keyword or Reserved 
Word Parameter Names 

The IKJNAME macro instruction can be 
used with the additional Parse macro 
instructions. 


Summary of Amendments 11 


Summary of Amendments 
for GC28-6764-1 
as Updated by GN28-2523 
Component Release 360S-OS-586 


Two new parameter blocks are described: 
DAPB, Entry Code X'34' 

DAIRACB - DAIR Attribute Control 
Block 


DYNAMIC SPECIFICATION OF DCB PARAMETERS 

New fields are defined for the following 
DAIR Parameter Blocks (DAPB )2 
Entry Code X'08' 

Entry Code X'lC 1 
Entry Code X'24' 

Entry Code X^O* 
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Summary of Amendments 
for GC28-6764-1 
OS Release 21 


LOGON PROCEDURE (Page 20) 

A error is corrected in Figure 1. 


INITIALIZATION OF THE TERMINAL MONITOR 
PROGRAM (Page 21) 

The length subfield of the PARM field 
of the LOGON EXEC statement is 
described. 


INVALID INFORMATION IN A JOB FILE CONTROL 
BLOCK (Page 32) 

A previously used job file control 
block may contain invalid information 
from an earlier used DCB. The problem 
and the procedure to circumvent this 
problem is clarified. 


ADDING COMMANDS TO THE TIME SHARING OPTION 
(Page 39) 

The method of adding a new member to 
SYSl.CMDLIB or concatenating a new 
command library to SYSl.CMDLIB is 
clarified. 


FORMATTING THE HELP DATA SET (Pages 40-42) 
Method of adding new information to the 
HELP data set is clarified. 


STAX MACRO INSTRUCTION (Pages 45,47) 

Clarification and guidance on the use 
of this macro have been added. 


PAIR PARAMETER BLOCKS (Pages 55-73) 

Miscellaneous changes, corrections, and 
clarifications have been added. 


DYNAMIC ALLOCATION INTERFACE ROUTINE (Pages 
52-54,74-79) 

Errors have been corrected, and new 
return codes have been added and others 
deleted for DAIR and Dynamic 
Allocation. Requirements for 
availability of a direct access device 
have been stressed. The description of 
the DAIR parameter list has been 
improved. 


TERM-TS PARAMETER (Page 84) 

Typographic error is corrected. 


STACK PARAMETER BLOCK (Pages 97-98) 

Corrections and clarifications are 
added. 


PUTLINE PARAMETER BLOCK (Page 128) 

Additional information on the PTPBOPUT 
field has been added. 


PUTGET PARAMETER BLOCK (Page 155) 
Corrections have been added. 


PUTGET Return Codes (Page 167) 

Clarifications and corrections have 
been made. 


TPUT MACR O INSTRUCTION (Pages 169-172) 

Describes the capability of the TJID 
operand when the macro is issued from a 
background program. 

Describes two new operands, HIGHP and 
LOWP. 

In addition, adds general 
clarifications to the TPUT description. 


TGET MACRO INSTRUCTION (Pages 174-175) 
Adds clarifications and corrections. 


TERMINAL CONTROL MACRO INSTRUCTIONS (Pages 
180-19 5) 

The following macro instructions have 
been moved from the Supervisor and Data 
Management Macro Instructions SRL to 
this book: 

GTSIZE, RTAUTOPT, SPAUTOPT, STATTN, 
STATUS, STAUTOCP, STAUTOLN, STBREAK, 
STCC, STCLEAR, STCOM, STSIZE, STTIMEOU, 
TCLEARQ. 

Clarifications and corrections have 
made throughout. 


COMMAND SCAN SERVICE ROUTINE (Page 197) 

Adds new topic to describe command name 
syntax for a user-written command. 


PARSE MACRO INSTRUCTIONS (Pages 213-215) 
Typographic errors are corrected. 
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QUOTED STRING NOTATION (Pages 215-216) 
The quoted string option SQSTRING is 
added to the IKJPOSIT macro 
instruction. 


TEST COMMAND (Pages 255-257,261) 

COPY, a new subcommand, and Assignment 
(=), an old subcommand previously 
omitted, have been added to the list of 
TEST subcommands. The use of symbolic 
addresses has been clarified. 


TSO CONTROL BLOCKS (Page 263) 

A legend has been added that describes 
the "bytes and alignment" column of 
each control block. 


ENVIRONMENT CONTROL TABLE (ECT) (Page 264) 
Errors have been corrected, and the 
tabulation has been clarified. 


PROTECTED STEP CONTROL BLOCK (PSCB) (Pages 
265-26 6) 

Errors have been corrected, and the 
tabulation has been clarified. 
Information on the default unit name 
(PSCBGPNM) has been added. 


TIME SHARING JOB BLOCK (Pages 267-269) 
New fields have been added and 
clarifications have been made. 


USER PROFILE TABLE (Page 270) 

Descriptions have been improved. 
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Summary of Amendments 
for GC28-6764-0 
as Updated by GN28-2484 
OS Release 20.1 


FLUSHING OF TGET AND TPUT BUFFERS 

When an attention interruption is 
received, the TGET and TPUT buffers are 
flushed. The contents of these buffers 
(if any) are lost. 


NEW RETURN CODES FROM PAIR 

The meaning of DAIR return code 32 has 
been changed. DAIR return code 44 has 
been added. 


NEW OPERAND ADDED TO THE STAX MACRO 
INSTRUCTION 

A new operand, DEFER=YES or NO, has 
been added to the STAX macro 
instruction to allow the deferring of 
attention processing. 


EDIT AND ASIS OPERANDS HAVE BEEN REDEFINED 
The descriptions of the EDIT and ASIS 
operands have been rewritten. These 
changes appear in the GETLINE, PUTLINE, 
and PUTGET macro descriptions as well 
as in the TGET and TPUT macro 
descriptions. 


TSEVENT MACRO INSTRUCTION, PPMODE, HAS BEEN 

DESCRIBED .. 

The TSEVENT macro instruction should be 
issued by a newly written Terminal 
Monitor Program, to update SMF records 
and the TSO Trace Writer entries. 


REVERSE MERGE INTO THE JOB FILE CONTROL 
BLOCK HAS BEEN DESCRIBED 

A previously used JFCB may contain 
invalid information obtained from an 
earlier used Data Control Block. 


NEW OPERANDS ON THE PUTGET MACRO 
INSTRUCTION 

The TERM and ATTN operands have been 
added to the PUTGET macro instruction. 
These operands affect especially the 
processing of I/O from an Attention 
Exit. 
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Introduction 


TSO, the Time Sharing Option of the IBM System/360 Operating System, 
consists of many, relatively small, functionally distinct modules of 
code. One major benefit of this modular construction is that the Time 
Sharing Option may be added to or modified to better suit the needs of 
the installation and each user. You can add to TSO, replace 
TSO-supplied code with your own, and delete those functions of TSO which 
you do not require. 

TSO is composed of modules that perform timing,, control, and 
accounting functions, and other modules that communicate with the user 
at the terminal and perform the work requested by him. 

Modifications to the control program portions of TSO should be made 
only by system programmers responsible for the proper functioning of the 
Time Sharing Option within the System/360 MVT configuration of the 
operating system. These modifications are discussed in the Time Sharing 
Option Guide . 

Each installation of the Time Sharing Option can replace those 
portions of TSO that communicate directly with the user at the terminal. 
The portions of TSO that communicate with the user are the Terminal 
Monitor Program (TMP) and the command processors. 

If you choose to write your own Terminal Monitor Program or command 
processors, you can use service routines, interface routines, and macro 
instructions, supplied with TSO or modified to support TSO, to provide 
many of the functions required by a TMP or a command processor. 


THE TERMINAL MONITOR PROGRAM (TMP) AND COMMAND PROCESSORS 

The Terminal Monitor Program is a reenterable problem program that 
accepts and interprets commands, and causes the appropriate command 
processors to be scheduled and executed. 

When a user logs on to TSO, he must specify, via the LOGON command, 
the name of a LOGON procedure. The program named in the EXEC statement 
in the LOGON procedure is attached during the log on as the Terminal 
Monitor Program. The program named in the EXEC statement can be either 
the TMP supplied with TSO, one provided by the installation, or one you 
have written yourself. 

Any Terminal Monitor Program must be able to communicate with the 
user at the terminal, fetch and pass control to command processors, 
respond to abnormal terminations at its own task level or at lower 
levels, and respond to and process attention interruptions. 

Once the log on has completed, the Terminal Monitor Program requests 
the user at the terminal to enter a command name. The TSO-supplied TMP 
writes a READY message to the terminal to request that a command be 
entered. The TMP determines if the response entered is a command, 
attaches the requested command processor, and the command processor 
performs the computing functions requested by the user at the terminal. 

You can write your own command processors and add them to the 
TSO-supplied command library; you can concatenate your own command 
library to the one supplied with TSO, or you can replace the entire TSO 
command library with your own. 


Introduction 17 



Command processors must be able to communicate with the user at the 
terminal, respond to abnormal terminations, process attention 
interruptions, and if required, fetch, pass control to, and respond to 
abnormal terminations of subcommand processors. 


BASIC FUNCTIONS OF TERMINAL MONITOR PROGRAMS AND COMMAND PROCESSORS 

You can see from the preceding discussion, that any Terminal Monitor 
Program and any command processor must provide four basic functions: 

1. Both the TMP and command processors must be able to communicate 
with the user at the terminal, 

2. The TMP must be able to fetch and pass control to a command 
processor. A command processor must be able to fetch and pass 
control to its subcommand processors if it has any. 

3. Both the TMP and command processors must be able to intercept and 
investigate abnormal terminations. 

4. Both the TMP and command processors must be able to respond to and 
process attention interruptions entered from the terminal. 

You can provide each of these functions to a Terminal Monitor Program 
or a command processor by using a service routine or a macro instruction 
provided with or modified to support TSO. 

Communicating with the User at the Terminal 

With TSO there are three ways a program can communicate with a user at a 
terminal: 

1. The BSAM or QSAM access methods. The major benefit of using BSAM 
or QSAM to process terminal I/O is that programs using these access 
methods do not become TSO dependent or device dependent and can 
execute either under TSO or in the batch environment. 

2. The STACK, GETLINE, PUTLINE, and PUTGET I/O service routines. 
Reached through the STACK, GETLINE, PUTLINE, and PUTGET macro 
instructions, the I/O Service routines provide the following 
functions: 

STACK - The STACK service routine establishes and changes the 
source of input by adding elements to or deleting elements from, an 
internally maintained input stack. The top element on the input 
stack determines the current source of input. 

GETLINE - The GETLINE service routine obtains all input lines other 
than commands or subcommands, and responses to prompting messages 
(a prompting message asks the user at the terminal to supply 
required information). The GETLINE service routine returns these 
lines of input from the input source designated by the top element 
of the input stack. 

PUTLINE - The PUTLINE service routine formats output lines, writes 
them to the terminal, and chains second level messages to be 
written out in response to a question mark from the terminal. 

PUTGET - The PUTGET service routine writes a message to the 
terminal and obtains a response from the terminal. A message 
written to the user at the terminal which requires a response is 
called a conversational message. 
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3. The TGET and TPUT supervisor call. A supervisor call routine, SVC 
93, is reached through the TGET and TPUT macro instructions. TGET 
and TPUT provide a route for I/O to a terminal. The functions are 
not as extensive, however, as those provided by the I/O service 
routines. 

Each of these methods performs different functions and is thus suited 
for particular I/O situations. The programmer designing his own TMP or 
command processor must understand which of the I/O methods best provides 
the I/O support required in different programming situations. 

Passing Control to Commands and Subcommands 

A Terminal Monitor Program must be able to recognize a command name 
entered into the system, fetch the requested command processor, and pass 
control to it. A command processor must be able to perform the same 
functions when a subcommand name is entered. 

You can use the Command Scan service routine to scan the input line 
for a syntactically valid command name or subcommand name, issue the 
BLDL macro instruction to search command libraries for the requested 
command processor or subcommand processor, and issue the ATTACH macro 
instruction to pass control to the requested routines. 

When you write a command processor or subcommand processor, you can 
use the Parse macro instructions to describe to the Parse service 
routine the operands that may be entered with the command name. You can 
then use the Parse service routine to determine which operands are 
present in the input buffer. The Parse service routine compares the 
information you supplied in the Parse macro instructions with the 
contents of the input buffer. This comparison indicates which operands 
are present in the input line. The Parse service routine returns a list 
to the calling routine, indicating which operands were found in the 
buffer. These operands indicate to the processing routines which 
functions the user at the terminal is requesting. 

Responding to Abnormal Terminations 

One of the responsibilities of a programmer coding a routine to run 
within TSO is to do all possible to keep that routine from causing the 
abnormal termination of TSO. If you write your own Terminal Monitor 
Program or command processors, you should use the STAE macro instruction 
and the STAI operand on the ATTACH macro instruction to provide error 
handling exits. 

Use the STAE macro instruction to provide the address of an error 
handling routine to be given control if any routine at the same task 
level as the error handling routine begins to terminate abnormally. 

Use the STAI operand on the ATTACH macro instruction to provide the 
address of an error handling routine to be given control if a routine at 
a lower task level begins to terminate abnormally. 

Responding to Attention Interruptions 

The Terminal Monitor Program and any command processor that accepts 
subcommands must be able to respond to an attention interruption entered 
from the terminal. An attention interruption is interpreted within TSO 
as a signal that the user may want to request a new command or 
subcommand. You must provide attention exits that can obtain a line of 
input from the terminal and respond to that input. 

Use the STAX service routine, reached through the STAX macro 
instruction, to build the control blocks and queues necessary for the 
system to recognize and schedule your attention handling routines. 
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OTHER FUNCTIONS PROVIDED WITH TSO 


Aside from the four basic functions provided by a Terminal Monitor 
Program or a command processor, other functions, peculiar to time 
sharing, can be obtained using routines provided with TSO. 


Two of these functions are: 


1. The dynamic allocation of data sets. 

2. The immediate, on-line testing of a newly written Terminal Monitor 
Program or command processor. 

These two functions are provided through the Dynamic Allocation 
Interface Routine (DAIR), and the TEST command processor. 


The Dynamic Allocation of Data Sets 

The LOGON procedure named in the LOGON command contains DD statements 
that define the data sets to be used during a TSO session, and other DD 
statements, called DD DYNAMS. These DD DYNAMS do not define data sets; 
they are used by Dynamic Allocation routines to provide data sets 
requested during program execution by a Terminal Monitor Program or a 
command processor. 

If you write your own Terminal Monitor Program or command processor, 
you can use the Dynamic Allocation Interface Routine (DAIR) to invoke 
Dynamic Allocation routines. Using DAIR, you can request Dynamic 
Allocation to: 

• Obtain the current status of a data set. 

• Allocate a data set. 

• Free a data set. 

• Concatenate data sets. 

• Deconcatenate data sets. 


Testing a Terminal Monitor Program or a Command Processor 

After you have coded a new Terminal Monitor Program or command 
processor, you will want to test it before you enter it into the Time 
Sharing Option. You can use the TEST command to do this. 

The TEST command permits a user at a terminal to test an assembly 
language program. You test a program by issuing the TEST command and 
the various TEST subcommands that perform the following basic functions: 

• Execute the program under test from its starting address or from any 
address within the program. 

• Display selected areas of the program as it appears in main storage, 
or display the contents of any of the registers. 

• Interrupt the program under test at a specified location or 
locations. 

• Change the contents of specified program locations in main storage 
or the contents of specific registers. 

In addition to these basic debugging functions, you can use the TEST 
command processor to display various control blocks, program status 
words, or a main storage map of the program being tested. 
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SUMMARY 


Most of the functions of a terminal monitor program or a command 
processor can be provided with macro instructions, service routines,, or 
supervisor call routines supplied with the Time Sharing Option, 

The following sections describe when and how to use these various 
macro instructions and routines. 
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The Terminal Monitor Program 


The Terminal Monitor Program (TMP) is a reenterable problem program that 
provides an interface between the terminal user, command processors, and 
the Time Sharing Control Program. The TSO LOGON/LOGOFF Scheduler 
attaches the TMP. The TMP is the program you name on the EXEC statement 
of your LOGON cataloged procedure. 


Specifying Data Sets at LOGON 


The volumes that contain your data sets cannot be mounted during a 
terminal session. The volumes must be mounted before the terminal user 
logs onto the system. The LOGON procedure indicated on the LOGON 
command contains DD statements that define the data sets to be used 
during the TSO session, and other DD statements, called DD DYNAM 
statements, that do not define data sets. These DD DYNAM statements 
provide blank entries in the Task Input Output Table and the Data Set 
Extension. These entries are available for the dynamic allocation of 
previously unallocated data sets. Figure 1 shows an example of a user 
LOGON procedure containing four DD DYNAM entries. For a complete 
discussion of a LOGON procedure, see Time Sharing Option Guide . 
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Figure 1. A LOGON Procedure Containing Four DD DYNAM Entries 

The Terminal Monitor Program you use can be the TMP supplied with 
TSO, or one provided by the installation, or one you have supplied 
yourself. If you choose to write your own Terminal Monitor Program, use 
the TSO service routines and macro instructions described in this book 
to help you code the TMP and fit it into the Time Sharing Option. 

The TMP must be able to respond to the following four conditions: 


1. Normal completion of a command processor or user program, and the 
requesting of another command. 

2. An error causing termination of the TMP, a command processor, or a 
user program. 

3. An attention request from the terminal, causing an interruption of 
the current program. 
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4. A STOP operator command, forcing a LOGOFF for the user. 

This section explains how to respond to these conditions. It 
describes in general terms how the TSO-supplied TMP functions, and how 
it fits together with the rest of the Time Sharing Option. For a more 
specific description of the TSO-supplied TMP, see the TSO Terminal 
Monitor Program and Service Routines PLM. 


Terminal Monitor Program Initialization 


When the TMP is attached by the LOGON/LOGOFF schedulers 

• Register 1 contains the address of the value found in the PARM field 
of the EXEC statement in the LOGON cataloged procedure. The 
TSO-supplied TMP uses this PARM value as the first command 
requested. The first two bytes of the PARM value are on a halfword 
boundary and contain the length of the PARM value. (The length 
value does not include the two length bytes.) 

• Register 13 contains the address of the register save area. 

• Register 14 contains the return address of the LOGON/LOGOFF 

scheduler. 

• Register 15 contains the entry point address of the TMP. 

The TMP sets up the tables and control blocks it requires, loads the 

TIME command processor, sets up the STAE and STAI exits to respond to 
abnormal terminations, sets up the attention exits, builds the command 
buffer, and initializes the input stack to point to the terminal. The 
TMP then uses the EXTRACT macro instruction to obtain the addresses of 
the STOP/MODIFY ECB and the Protected Step Control Block (PSCB) built by 
the LOGON/LOGOFF scheduler. 

The TSO-supplied Terminal Monitor Program attaches the command 
processor named in the EXEC statement PARM field. If no command was 
named as a PARM operand, the TMP issues a PUTGET macro instruction to 
obtain the first command. The TMP shares subpool 78 with the attached 
command processor but does not share subpool 0. The command processor, 
in turn, must share subpool 78 with any lower level tasks. 


Requesting a Command 

Figure 2 summarizes the steps taken by a Terminal Monitor Program to 
obtain a command, to pass control to that command , and to detach that 
command when it has finished processing. 
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Figure 


Requesting a Command 


To request a command from the terminal, use the PUTGET service 
routine• The PUTGET service routine first writes a line to the terminal 
to inform the user that another command is expected, then returns a line 
entered in response to the request, and places that line into a command 
buffer* 

Use the Command Scan service routine to determine that the line of 
input is a syntactically valid command name. 


Use the BLDL macro instruction to search the command library or 
libraries for the command processor load module indicated by the command 
name, and use the ATTACH macro instruction (specifying a STAI exit 
routine) to pass control to the requested command processor. 
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Your TMP must create any parameters expected by the command processor 
and pass them to the newly attached command processor. The TSO-supplied 
TMP passes the address of a Command Processor Parameter List in register 
one. See the section headed "Interface with the I/O Service Routines". 

When the command processor completes, the TMP issues a DETACH macro 
instruction for it, uses the DAIR service routine to mark dynamically 
allocated data sets available to be freed, and uses the PUTGET service 
routine to obtain another command. 

Please note that the use of an installation-supplied program in place 
of the Terminal Monitor Program can result in invalid values for the 
core occupancy time field in SMF record 34, and may cause invalid TSO 
Trace Writer entries. This situation occurs only when a single user is 
assigned to a foreground region and the installation-supplied program 
runs to completion without being swapped out of main storage. 

To avoid this problem, your user-written Terminal Monitor Program 
should issue the TSEVENT macro instruction, specifying the PPM0DE 
operand, before attaching each command processor and after each command 
processor returns. This issuance of the TSEVENT macro instruction 
causes SMF record 34 and the TSO Trace Writer entries to be updated. 

Issue the TSEVENT macro instruction as follows: 

1. Set register one to point to the first character of the command 
name being attached or released. 

2. Set the high order bit in register one to: 

1 if the command processor is beginning execution. 

0 if the command processor is ending. 

3. Code the TSEVENT macro instruction as shown in Figure 3. 

r- t-t- 1 

| [label] I TSEVENT | PPMODE j 

L-X-X-J 

Figure 3. The TSEVENT Macro Instruction Specifying PPMODE 


Intercepting an ABEND 


The Terminal Monitor Program must be able to recognize and respond to 
two basic types of ABEND situations: 

1. An attached subtask, for example a command processor, is 
terminating abnormally. 

2. The TMP itself or a program linked to by the TMP, for example TEST 
or Command Scan, is terminating abnormally. 


INTERCEPTING A SUBTASK ABEND 

When a subtask of the Terminal Monitor Program begins to terminate 
abnormally, the TMP STAI exit, specified by the TMP when it attached the 
subtask, receives control. The TMP STAI exit receives control under the 
TCB of the abending subtask. The subtask will already have performed 
its own STAE processing, if any was specified. Figure 4 shows the 
ABEND, STAE, STAI relationship. 
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Figure 4* ABEND, STAE, STAI Relationship 


The TMP must inform the user at the terminal of the ABEND situation, 
and allow the user to enter another command at this time. Use the 
PUTGET service routine, specifying the TERM operand, to inform the user 
of the ABEND and to return a line of input from the user. 

The terminal user has four options : 

1. He can allow the ABEND to continue by entering a null line 
(carriage return). 

2. He can stop processing of the ABEND by entering a command name 
other than TEST or TIME. 


3. He can request any secondary messages concerning the terminating 
program by entering a question mark. 


26 Guide to Writing a TMP or a CP (Release 21.6) 




4- He can place the terminating program under the control of the TEST 
command processor by entering the command name TEST. 

Use the Command Scan service routine to determine what the user has 
entered at the terminal. 

If he enters a null line, the TMP returns control to the ABEND 
routine, and the task is allowed to terminate abnormally. If he enters 
a command name, other then TEST and TIME, the TMP processes the new 
command name after detaching the incomplete subtask. 

If the user enters a question mark, the PUTGET service routine causes 
the secondary level informational message chain (if one exists) to be 
written to the terminal, again puts out the message, and returns the 
response from the terminal. 

If the user enters the command name TEST, the TMP passes control to 
the TEST command processor via a LINK macro instruction. If any 
operands were entered on the TEST command, the TMP detaches all subtasks 
before linking to the TEST command processor. If no operands were 
entered, the TMP does not detach any currently active subtasks. The 
user is requesting that the abnormally terminating task be run under the 
control of TEST. 

When the TMP links to the TSO-supplied TEST command processor, 
register one must contain a pointer to a Test Parameter List (TPL)• 
Figure 5 shows the format of the Test Parameter List you must build and 
pass to the TEST command processor. 


Number of 
Bytes 


Field 


Contents or Meaning 


H 


TPLCBUF 


The address of the Command buffer used by the 
last attached command processor. 


H 


TPLUPT 


The address of the User Profile Table (UPT). 
The UPT is built by the LOGON/LOGOFF 
scheduler from information stored in the User 
Attribute Data Set (UADS) and from 
information contained in the LOGON command. 
The address of the UPT is found in the 
PSCBUPT field of the Protected Step Control 
Block (PSCB). See Appendix A for the format 
of the UPT. 


H 


TPLPSCB 


TPLECT 


The address of the Protected Step Control 
Block (PSCB). The PSCB is built by the 
LOGON/LOGOFF scheduler from information 
stored in the UADS. The TMP can obtain the 
address of the PSCB with the EXTRACT macro 
instruction, see Appendix A for the format 
of the PSCB. 

+ - 

The address of the Environment Control Table 

(ECT). The ECT must be built by the TMP 
during its initialization process and is used 
by the TS0 service routines. See Appendix a 
for the format of the ECT. 


Figure 5. The Test Parameter List (Part 1 of 3) 
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r i 

Number of 
Bytes 

r ~ i 

Field 

r ~ i 

Contents or Meaning 

. i 

4 

. . 

TPLTBUF 

. 

The address of the TEST command buffer. The 
TEST command buffer contains the TEST command 
and all operands entered by the terminal 
user. The variable length command buffer is 
located in subpool 1. It is preceded by a 
four-byte header consisting of a two byte 
length field and a two byte offset field. 

The length field contains the total length of 
the buffer including the four bytes of header 
information. 

........ _ .. ...... .... . . ... . j 

r —- - 

4 

L 

TPLCTCB 

The address of the Task Control Block (TCB) 
of any attached command processor. A value 
of zero is placed in this field when the 
command processor is detached. Both the TMP 
and the TEST command processor are 
responsible for maintaining this field. 

... .. .... . . .. 

1 

4 

L 

r _._ _.- _. 

TPLSTAI 

The address of the TMP STAI exit routine 
specified as an operand of the ATTACH macro 
instruction issued by the TMP to attach the 
current command processor. This exit routine 
gains control when the attached command 

processor begins to terminate abnormally. 

... _. ... . .. .. .._. _. 

r - 

4 

TPLSPLS 

L ... ... 

The address of the STAI exit parameter list 
specified on the ATTACH macro instruction 
issued by the TMP to ATTACH the current 
command processor. 

_.. . _ _ __ _ j 

r~ 

4 

_ _. 

r ~ * 

TPLNECB 

This four-byte field contains an Event 

Control Block (ECB) belonging to the TMP STAI 
exit routine which gets control when a 
command processor terminates abnormally. 

This ECB must be posted by either the TMP or 
the TEST program before the abnormally 
terminating command processor can resume 
processing. A post code of X'7F* indicates 
that a recovery is being attempted. Any 
other post code causes the ABEND to continue. 

4 

TPLNTCB 

. 

The address of the Task Control Block (TCB) 
in control when a command processor started 
to terminate abnormally. The TMP should set 
this field to zero if the TEST program is 
invoked by the Attention exit routine. 

L _ ..... 

4 

1 

L - 

TPLMECB 

This four-byte field contains an Event 

Control Block (ECB) used by TSO to STOP a 
terminal user's session. When this ECB is 
posted, the TEST program should return to the 
TMP as soon as possible. The TMP then must 
take the appropriate action to DETACH any 
subtasks before returning to the LOGON/LOGOFF 
Scheduler for a terminal disconnect. 

L — J 


Figure 5. The Test Parameter List (Part 2 of 3) 
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f- + - + — 

TPLCECB 


Number of 
Bytes 


Field 


(Contents or Meaning 


TPLIECB 


TPLAECB 


I 

-+- 


RESV 


Figure 5. 


|The address of an Event Control Block (ECB) 
jused by the MVT control program to indicate 
j the termination of an attached task. This 
| ECB address is the one you specify as the ECB 
|operand on the ATTACH macro instruction 
|issued to attach the command processor. 

|The address of an Event Control Block (ECB) 

|used by the TMP STAI exit routine to indicate 
| that the attached command processor is 
(terminating abnormally. 

|The address of an Event Control Block (ECB) 
(used by the TMP Attention exit routine to 
(indicate that an attention interruption has 
(occurred. | 

+- 4 

(Reserved. | 
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When the TEST Command processor returns control to the TMP, use the 
PUTGET service routine to obtain a new command. 


INTERCEPTING A TMP TASK ABEND 

When the TMP (or any program linked to by the TMP except TEST) causes an 
ABEND, the TMP STAE exit gains control. The TMP specifies its own STAE 
exit routine by issuing the STAE macro instruction. (See Supervisor 
Services and Macro Instructions for a discussion of the STAE macro 
instruction.) 

Your TMP STAE exit routine can use the contents of the STAE work area 
created by the STAE macro instruction to determine the type of error, 
the cause of the error, the PSW at the time of the ABEND, the last PSW 
before the program ABEND, and the contents of the program registers. 

If your TMP STAE exit routine cannot correct the problem, it should 
use the PUTLINE macro instruction to inform the user at the terminal 
that a task running under the TMP TCB is terminating abnormally, take a 
dump of the user's region if a SYSABEND or a SYSUDUMP data set was 
specified in the user's LOGON cataloged procedure, clear the user's 
region, then load a fresh copy of the TMP, and begin processing as if 
the TMP had been invoked by the LOGON/LOGOFF Scheduler. 

If the error persists; that is, the TMP fails again, control should 
pass to the PUTLINE service routine to notify the user. A log off 
should be forced by returning to the LOGON/LOGOFF Scheduler. 
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Processing an Attention Interruption 

After having been attached by the LOGON/LOGOFF Scheduler, the TMP must 
set up its attention handling facilities during its initialization 
process. You can use the STAX macro instruction to pass the address of 
your attention handling routine to the system. 

Several attention handling routines may be enqueued at any one time; 
that is, both the TMP and the currently active command processor may 
have issued STAX macro instructions. The attention exit routine 
specified by the last attached task is the one given control if one 
attention interruption occurs. 

The attention handling routine you specify for the Terminal Monitor 
Program is given control under any of the following conditions: 

1. An attention interruption is entered from the terminal while the 
Terminal Monitor Program is in control. 

2. An attention interruption is received from the terminal while a 
program other than the Terminal Monitor Program is in control, but 
that program has not provided an attention handling routine. 

3. A program other than the Terminal Monitor Program is in control. 

The program has provided an attention exit, but the user at the 
terminal has issued sufficient attention interruptions to reach the 
Terminal Monitor Program*s attention handling routine. As an 
example, if a command processor that has provided an attention 
handling routine is in control, and a user enters two successive 
attention interruptions from the terminal, the Terminal Monitor 
Program*s attention exit receives control. 

You can defer attention interruption processing with the DEFER 
operand of the STAX macro instruction. If you do use the DEFER option, 
attention interruptions are queued as they are received, and are not 
processed until you request that the DEFER option be removed. 


PARAMETERS RECEIVED BY ATTENTION HANDLING ROUTINES 


When your attention exit routine is entered, the registers contain the 
following information: 


Register 


Contents 


0,2-12 

1 

13 

14 

15 


Irrelevant 

The address of the Attention Exit Parameter List. 

Save area address. 

Return address. 

Entry point address of the attention handling routine. 


The Attention Exit Parameter List pointed to by register one, 
contains the address of a Terminal Attention Interruption Element 
(TAIE) . 


The parameter structure received by your attention exit routine is 
shown in Figure 6. 
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Figure 


Entry from the STAX service routine 




6. Parameters Passed to the Attention Exit Routine 
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The Attention Exit: Parameter List 


Figure 7 shows the format of the Attention Exit Parameter List pointed 
to by register one when an attention exit routine receives control. 


r - T 

Number of 


Bytes 


Field 


Contents or Meaning 


-H 


The address of the Terminal Attention 
Interrupt Element (TAIE). 

+--1 

The address of the input buffer you specified 
as the IBUF operand of the STAX macro 
instruction. Zero if you did not include the 
IBUF operand in the STAX macro instruction. 

-----H 

The address of the user parameter information 
you specified as the USADDR operand of the 
STAX macro instruction. ZERO if you did not 
exclude the USADDR operand in the STAX macro 
instruction. 


Figure 7. The Attention Exit Parameter List 


The Terminal Attention Interrupt Element (TAIE) 

The first word of the Attention Exit Parameter List contains the address 
of an eighteen-word Terminal Attention Interrupt Element (TAIE). Figure 
8 shows the format of the TAIE. 


r -«- T ~-—-T-----'-*-----1 

| Number of | | | 

| Bytes | Field |Contents or Meaning | 

j.--+--j--—--“H 

| 2 | TAIEMSGL |The length in bytes of the message placed | 


into the input buffer you specified as the 
IBUF operand on the STAX macro instruction. 
Zero if you did not code the IBUF operand in 
the STAX macro instruction. 


|-+-+-- 1 

| 1 | TAIETGET |The return code from the TGET macro | 

| | (instruction issued to get the input line fromj 

j | |the terminal. | 

I--f-f--1 

| 1 | (Reserved. | 

| 4 | TAIEIAD | Interruption address. The right half of the j 

j | | interrupted PSW. The address at which the j 

j | | program (or a previous attention exit) was j 

| | |interrupted. j 

I-1-1- ---f 

| 64 | TAIERSAV |The contents of general registers, in the | 

| | (order 0 - 15, of the interrupted program. | 

L_ X _ X _J 

Figure 8. The Terminal Attention Interrupt Element 
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If you did not include the IBUF and the OBUF operands in the STAX 
macro instruction that set up the attention handling exit, use the 
PUTGET macro instruction, specifying the TERM operand, to send a mode 
message to the terminal identifying the program that was interrupted, 
and to obtain a line of input from the terminal. 

If you specify the OBUF operand on the STAX macro instruction without 
an IBUF operand, or with an IBUF length of 0, you can then use the 
PUTGET macro instruction, specifying the ATTN operand. This causes the 
PUTGET service routine to inhibit the writing of the mode message, since 
a message was already written to the terminal from the output buffer 
specified in the STAX macro instruction. The PUTGET service routine 
merely returns a logical line of input from the terminal. 

In either of the above cases, if the user enters a question mark, the 
PUTGET service routine automatically causes the secondary level 
informational message chain (if one exists) to be written to the 
terminal, again puts out the mode message, and returns a line from the 
terminal. 

If you used the IBUF operand on the STAX macro instruction, note that 
no logical line processing or question mark processing is performed. If 
the user returns a question mark, you will have to use the PUTLINE macro 
instruction to write the secondary level informational message chain to 
the terminal. Then issue a PUTGET macro instruction, specifying the 
TERM operand, to write a mode message to the terminal and to return a 
line of input from the terminal. 

Use the Command Scan service routine to determine that the line of 
input is syntactically correct in the input buffer returned by the 
PUTGET service routine, or in the attention input buffer (pointed to by 
the second word of the Attention Exit Parameter List). 

Special functions such as the TIME function should be performed 
immediately by the attention handling routine, and a new READY message 
should then be put out to the terminal, so that the terminal user may 
enter another command. 

Any other command should be passed to the TMP mainline routine for 
processing as if it were a newly entered command. 

Note that the TGET and TPUT buffers are flushed when an attention 
interruption is entered. If the user enters an attention interruption 
from the terminal and then enters a null line to continue processing, 
the contents, if any, of the TGET and TPUT buffers are lost. 


Processing a STOP Command 

A STOP/MODIFY ECB is created by the time sharing system and can be 
obtained by your TMP by use of the EXTRACT macro instruction. During 
TMP processing, if a STOP command is indicated by a post to the STOP 
ECB, return to the LOGON/LOGOFF Scheduler so that the user may be logged 
off the system. 
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Command Processors 


A command processor is a problem program invoked by the TMP when a user 
at a terminal enters a command name. 

The internal logic of the TSO-supplied command processors is 
described in the TSO Command Processor PLM . The command language used 
to request each of these command processors is described in the TSO 
Command Language Reference . 

If you choose to write your own command processors, you should be 
familiar with the Service Routines described in this book. 

This section discusses the relationships between the command 
processors and the rest of the Time Sharing Option, and provides 
guidelines for coding your own command processors. 

The section is divided into the following topics: 

• Response Time - Discusses the steps you should take to insure that 
your command processor does not adversely affect system response 
time. 

• Command Processor Use of the TSO Service Routines - Briefly 
discusses each of the TSO Service Routines and the situations in 
which they should be used. 

• The STAE and STAI Exit Routines - Discusses the functions your error 
routines should provide. 

• Attention Exit Routines - Discusses the need for attention handling 
exits and the functions those exits should perform. 

• Adding Commands to the Time Sharing Option - Discusses the methods 
you can use to place a newly written command processor into the Time 
Sharing Option. 

• The HELP Data Set - Discusses the HELP data set, private HELP data 
sets, and the means of entering information into a HELP data set. 

Programming Note : In TSO, assembly language programs may fail or cause 
a performance impact when they use the same job file control block 
(JFCB) more than once for the same data set. When the data set is 
opened, the Open routine fills any unspecified fields in the data 
control block from information in the data set control block (DSCB) and 
the job file control block. The Open routine then does a "reverse 
merge" from the data control block back into the job file control block, 
filling zeroed or unspecified fields in the job file control block. If 
the same data set is reopened by a later program by use of a new OPEN 
macro instruction, the Open routines will retrieve old information from 
the job file control block for fields not specified in the data set 
control block. The retrieved information could be unwanted for the new 
use of the data set and therefore could cause program failure or 
performance impact. Examples of such unwanted information include key 
length for BSAM and QSAM, and buffer size or channel program parameters 
for QSAM. 

If any of your command processors specify DCB information which could 
cause a failure on a subsequent use of a JFCB, you can follow the 
procedure outlined below to inhibit the reverse merge from the DCB back 
into the JFCB. 
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1. Issue a RDJFCB macro instruction to read the JFCB into your own 
main storage. 

2. Set the JFCBTSDM field (offset 52 decimal, 34 hex in the Job File 
Control Block) to X f 0A' to inhibit the DCB to JFCB merge, 

3. Issue an OPEN macro instruction specifying TYPE=J. 


For a discussion of the RDJFCB macro instruction and the OPEN macro 
instruction type J, see Data Management for System Programmers . 


Response Time 


A Time Sharing system depends upon fast response. If you write your own 
command processors to run under the IBM Time Sharing Option, your 
command processors will directly affect system response time. The 
following recommendations are included to help you keep system response 
time to a minimum. 


PROGRAM DESIGN 

Any command processors you write should not modify themselves in any way 
during their execution. They should obtain all work areas with a 
GETMAIN macro instruction so that the in-line code remains unchanged. 
This allows the command processor to be executed from the Time Sharing 
Link Pack Area, and used by several tasks concurrently. 

TSO provides, along with the system Link Pack Area, a Time Sharing 
Link Pack Area. Figure 9, a storage map of MVT with the Time Sharing 
Option, shows the Time Sharing Link Pack Area within the Time Sharing 
Control Region. 

Frequently used Command Processors can be placed in the Time Sharing 
Link Pack Area. Placing programs in the Time Sharing Link Pack Area 
reduces the amount of time required to access them since they are 
resident in the system and need not be brought in from an external data 
set. 

Besides reducing access time, placing command processors in the Time 
Sharing Link Pack Area provides two additional benefits: 

1. Swap time is reduced. Swap time is the time required to move one 
user’s programs and data from a foreground region to a swap data 
set and to move the next user's programs and data from a swap data 
set back into the foreground region. 

One of the factors that affects swap time is the amount of data 
that must be swapped. If the currently active command processor is 
executing from the Time Sharing Link Pack Area, it is not swapped 
when the foreground region is swapped. You therefore swap less 
data if your command processors are resident in the Time Sharing 
Link Pack Area than if they execute from the foreground region. 

See Time Sharing Option Guide for a discussion of the swapping 
algorithms used in TSO. 


Command Processors 35 



2. If you are running several foreground regions, your total storage 
requirement is less if frequently used command processors are 
resident in the Time Sharing Link Pack Area. Command processors 
resident in the Time Sharing Link Pack Area can be executed for any 
foreground region and need not be loaded into those regions. Your 
foreground regions may therefore be smaller if some of the larger 
command processors can be executed in the Link Pack Area. 


/__ _ _/l 


Link Pack Area 


Master Scheduler 


TCAM 

Message Control Program and Buffers 


Time Sharing Control Region 

• Time Sharing Control Task 

• Region Control Task 

• TSO Driver 

• Time Sharing Link Pack Area 

• Buffers 



Foreground (TSO) Region 

• Terminal Monitor Program 




Local System Queue Area 



- 


Background (Batch) Regions 






/f 

H UK 1 


m 

System Queue Area 

1 

MVT Nucleus 

i 


Figure 9. Storage Map - MVT with Time Sharing Option 
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MODULE SIZE AND STORAGE REQUIREMENTS 


Command processors that do not execute in the Time Sharing Link Pack 
Area should be designed to minimize the average amount of data swapped. 

The more a command processor interacts with a user, the more often it 
must wait for input from the terminal. Since programs waiting for input 
from the terminal are eligible to be swapped, the probability is great 
that the program will be swapped. If a command processor is large and 
is likely to be swapped several times before it can complete its 
function, consider dividing it into several load modules to reduce the 
amount of data swapped. Keep in mind however, that additional time is 
required to perform a BLDL and a fetch for each of the additional load 
modules. 

Keep in mind also that the device type used to contain the swap data 
sets affects the amount of time for each swap. See storage Estimates 
for block sizes swapped to various device types. 


Command Processor Use of the TSO Service Routines 

Use the TSO-provided service routines described in this manual when 
coding your own command processors. Read the sections on the various 
service routines and macro instructions for an understanding of what 
services they perform and how to use them. The following topics provide 
information on when to use each of the service routines. 


STACK SERVICE ROUTINE 

Use the STACK service routine to change the source of input by adding an 
element to the input stack, and to reset the input stack to the terminal 
element originally specified by the Terminal Monitor Program. 

A command processor should issue the STACK macro instruction in the 
following circumstances: 

1. Your command processor has created a series of commands to be 
executed after the command processor terminates. The command 
processor builds an in-storage list containing the commands to be 
executed and uses the STACK macro instruction to place a pointer to 
the list on the input stack. 

2. You may want to pass data from one of your command processors to 
another command processor. This data may be passed in storage via 
the input stack. Issue the STACK macro instruction to place a 
pointer to the in-storage data on the input stack. 

3. If you write a command processor to perform functions similar to 
those performed by the TSO-supplied EXEC command, (that is, to 
execute a command procedure), issue the STACK macro instruction to 
place a pointer on the input stack to the command procedure to be 
executed. 

4. Whenever one of your command processors terminates with an error 
condition, its error handling routine should issue the STACK macro 
instruction to reset the input stack. 
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GETLINE SERVICE ROUTINE 


Your command processors should use the GETLINE service routine to obtain 
data. The buffer returned by GETLINE is in subpool 1 and is owned by 
your command processor. If your command processor issues multiple 
GETLINE macro instructions, it should free the buffers either with the 
DETACH or the FREEMAIN macro instructions. 


PUTLINE SERVICE ROUTINE 

Your command processors should use the PUTLINE service routine to write 
informational messages or data to the terminal and to chain second level 
informational messages. PUTLINE writes the output lines to the terminal 
regardless of the source of input. 


PUTGET SERVICE ROUTINE 

Your command processors should use the PUTGET service routine for 
prompting and for subcommand requests. Use the operands on the PUTGET 
macro instruction to specify logical line processing with editing and 
the WAIT option. 

If the user at the terminal enters a question mark in response to a 
message issued with a PUTGET macro instruction, the PUTGET service 
routine prints the second level messages chained by previous PUTLINE 
macro instructions. If the user responds with a subcommand name, the 
second level messages are deleted and the storage they occupied is 
freed. See the topic headed "PUTGET Processing" for exceptions to this 
usual method of processing. 

As with the GETLINE service routine, the buffers returned by the 
PUTGET service routine belong to, and should be freed by, the command 
processor. 

DAIR SERVICE ROUTINE 

Your command processors should use the DAIR service routine to allocate 
and free data sets and to obtain information concerning data sets. 
Command processors should allocate data sets by DSNAME and use the 
DDNAMES returned by DAIR — if necessary passing them on to any 
subcommands or problem programs running under the command processor. 

Whenever the user specifies a password for a data set, the password 
should be passed by the command processor to DAIR when allocation is 
requested. 

Command processors that accept subcommands should use the DAIR 
service routine to mark any data sets allocated by the subcommands as 
allocatable before detaching the terminated subcommand. 


COMMAND SCAN SERVICE ROUTINE 

Your command processors should use the Command Scan service routine to 
scan for valid subcommand names. The option of checking the remainder 
of the input line for non-separator characters should be requested. If 
no additional significant characters are found in the line, the command 
processor subroutine need not invoke the PARSE service routine to scan 
the command operands (none will be present). 
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PARSE SERVICE ROUTINE 


Your command processors aiid subcommand processors should use the PARSE 
service routine to scan the operands entered with the command or 
subcommand name. The PARSE service routine returns a Parameter 
Descriptor List to the calling routine. The Parameter Descriptor List 
describes the operands found in the command buffer. 

Command processors and subcommand processors can specify to PARSE 
that validity checking exits be taken on certain types of operands. 
Since the PARSE Service routine checks the operands only for syntax 
errors, you should specify that validity checking routines be entered 
whenever a logical, rather than a syntactical, error might occur. 


STAE/STAI Exit Routines - Intercepting an ABEND 


Use the STAE and STAI exits in your command processors to keep the 
system operable if abnormal termination occurs. STAE/STAI exits should 
be used in such a way that the command processor gets control if a 
subcommand abnormally terminates. STAE provides the command processor 
with the ability to intercept an ABEND so that cleanup, bypass, and if 
possible, execution retry can be accomplished. (See Data Management for 
System Programmers , for a discussion of the STAE macro instruction. See 
Supervisor Services and Macro Instructions for a a discussion of the 
STAI operand of the ATTACH macro instruction.) 

The following types of command processors should use STAE exit 
routines: 

• All command processors that process subcommands. 

• All command processors that request system resources that are not 
freed by ABEND or DETACH. 

• Command processors that process lists., to allow processing of other 
elements in the list if a failure occurs while processing one 
element in the list. 

Command processors that attach subcommands should also provide a STAI 
exit to intercept abnormally terminating subcommand processors. 

STAE and STAI exit routines should observe the following guidelines 2 

1. The error handling exit routine should issue a diagnostic error 
message of the form: 

1st level command name ENDED DUE TO ERROR 

subcommand name 

2nd level COMPLETION CODE IS xxxx 

where the name supplied in the first level message is obtained from 
the Environment Control Table, and the code supplied in the second 
level message is the completion code passed to the STAE or STAI 
exit from ABEND. 

The routine should issue these messages so that the original cause 
of abnormal termination is recorded should the error handling exit 
itself terminate abnormally before diagnosing the error. 
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When an ABEND is intercepted, the command processor STAE exit 
routine should determine whether retry is to be attempted. If so, 
the exit routine should issue the diagnostic message and return, 
indicating via return code that a STAE retry routine is available. 
If a retry is not to be attempted, the exit routine should return, 
indicating via return code that no retry is to be attempted. The 
TMP STAI exit routine will issue the diagnostic message. (For a 
description of the return codes and their meanings, see Supervisor 
Services and Macro Instructions .) 

2. The STAE or STAI routine that receives control from ABEND should 
perform all necessary steps to provide system cleanup. This 
cleanup should be performed in the STAE exit routine rather than in 
the STAE retry routine because DETACH with the STAE=YES operand 
does not allow the subtask to retry from a STAE/STAI exit. 

3. The error handling exit routine should attempt to retry program 
execution when possible. If the command processor can circumvent 
or correct the condition that caused the error, the error handling 
routine should attempt to do so. In other cases, however, RETRY 
has no function and the command processor STAE exit should not 
specify the RETRY option. 


Attention Exit Routines 


An attention exit routine should be provided by any command processor 
that accepts subcommands. Use the STAX macro instruction to specify the 
address of your attention handling routine, see the section headed 
"ATTENTION INTERRUPTION HANDLING - THE STAX SERVICE ROUTINE", for a 
complete discussion of the STAX macro instruction. 

If you did not include the IBUF and the OBUF operands in the STAX 
macro instruction that set up the attention handling exit, use the 
PUTGET macro instruction, specifying the TERM operand, to send a mode 
message to the terminal identifying the program that was interrupted, 
and to obtain a line of input from the terminal. 

If you specify the OBUF operand on the STAX macro instruction without 
an IBUF operand, or with an IBUF length of 0, you can then use the 
PUTGET macro instruction, specifying the ATTN operand. This causes the 
PUTGET service routine to inhibit the writing of the mode message, since 
a message was already written to the terminal from the output buffer 
specified in the STAX macro instruction. The PUTGET service routine 
merely returns a logical line of input from the terminal. 

In either of the above cases, if the user enters a question mark, the 
PUTGET service routine automatically causes the secondary level 
informational message chain (if one exists) to be written to the 
terminal, again puts out the mode message, and returns a line from the 
terminal. 

If you used the IBUF operand on the STAX macro instruction note that 
no logical line processing or question mark processing is performed. If 
the user returns a question mark, you will have to use the PUTLINE macro 
instruction to write the secondary level informational message chain to 
the terminal. Then issue a PUTGET macro instruction, specifying the 
TERM operand, to write a mode message to the terminal and to return a 
line of input from the terminal. 

Whether you use the IBUF operand on the STAX macro instruction or the 
PUTGET macro instruction to return a line from the terminal, you can use 
the Command Scan service routine to determine what the user has entered. 
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If the user enters a null line f the attention handling routine should 
return to the point of interruption. Note however, that the TGET and 
TPUT buffers are flushed during attention interruption processing. If 
any data was present in these buffers, it is lost. 

If a new command or subcommand is entered, the attention handling 
routine should: 

• Reset the input stack. 

• Post the command processor's Event Control Block to cause active 
service routines to return to the command processor. 

• Exit. 


Adding Commands to the Time Sharing Option 

There are two methods you can use to place a new command processor into 
the Time Sharing Option. You can enter your newly written command 
processor as a member of the partitioned data set SYSl.CMDLIB, via the 
Linkage Editor, or you can create your own command library and 
concatenate it to the SYSl.CMDLIB data set. In the latter case, use the 
utility IEBUPDTE to create new statements in the link list (LNKLSTOO) in 
SYSl•PARMLIB. If you choose to concatenate your library to SYSl.CMDLIB, 
note that you cannot do it during a terminal session. You must 
concatenate the two libraries with data definition statements within 
your LOGON procedure. The DDNAME must be STEPLIB. 

See Data Management Services for information on creating data sets, 
entering members into data sets, and concatenating data sets. 


The HELP Data Set 

A terminal user can enter the HELP command to retrieve information about 
commands and subcommands. This information is stored in a data set 
labeled SYSl.HELP (the HELP data set). If you add command processors to 
the Time Sharing Option, you should either add HELP information to the 
existing SYSl.HELP data set, or create your cwn private HELP data set. 

SYSl.HELP is a cataloged, partitioned data set consisting of one 
member, named "COMMANDS", and individual members for each command in the 
system. The 'COMMANDS' member contains a list of the commands available 
to the user, and a brief description of each. The individual members 
for each command are named with the command name, and contain more 
specific information about the command and its subcommands. The HELP 
information contained within any member of the HELP data set consists of 
card images. The logical record length is therefore 80 characters. 

Each of the SYSl. HELP members, other than the "COMMANDS" member, is 
divided into the following subgroups, each of which can be displayed at 
the terminal: 

• A subcommand list - This information appears only if the command has 
subcommands. 

• Functional description - This subgroup provides a brief description 
of the function of the command or subcommand. 

• Syntax - This information describes the syntax of the command or 
subcommand. 


Command Processors 41 



• Operand description - This subgroup provides information on the 
command positional operands, followed by individual sections 
containing brief descriptions of each keyword and its parameters. 


PRIVATE HELP DATA SETS 

Private HELP data sets must be structured exactly like the SYS1.HELP 
data set, since both data sets are processed alike. 

You may concatenate your data set to the SYS1.HELP data set (or vice 
versa) but the data sets must have the same attributes. Concatenated 
data sets are searched in the order of concatenation. If SYS1.HELP and 
a private HELP data set have been concatenated, the first 'COMMANDS' 
member encountered by the HELP processor is used as the list of 
available commands. Thus, if you concatenate your own HELP data set to 
SYS1.HELP, you should make additions to the "COMMANDS" member of 
SYSl.HELP. 


FORMATTING THE HELP DATA SET 

Use the IEBUPDTE utility program to update SYSl.HELP. Use the 
information described in Figure 10 to format the data set when you add 
to SYSl.HELP or set up your own HELP data set. The control characters, 
beginning in card column 1, divide the data set into the subgroups 
previously described, and thereby permit the HELP command processor to 
select message text according to the operands supplied on the terminal 
user's HELP command. (See TSO Command Language Reference for a 
discussion of the HELP command.) 
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Control 

Character 


Purpose of Data Card 


This card indicates that a list of commands or 
subcommands follows. 


This card indicates that the functional discussion of 
the command or subcommand follows. 


This card indicates that the syntax description of the 
command or subcommand follows. 


This card indicates that the command operands and 
their descriptions follow. Positional operands must 
follow immediately after the ")0" control card and 
before the ")) keyword" control cards. 


))keyword 


This card indicates that information follows 
describing the named keyword. One of these control 
cards must be present for each KEYWORD operand within 
the command. Each card contains the name of the 
keyword it describes. 


j=subcommandname|This card indicates that information follows j 
| (concerning the subcommand named after the equal sign, j 
| |One of these cards is required for each subcommand | 
j |accepted by the command being described. Note that j 
j |this card merely names the subcommand; it does not j 
| |describe it. Describe the subcommand in the same | 
| |manner you would describe a command. j 
| | If the subcommand has an alias name, you may | 
| |include the alias name on the control card, i.e. | 
| | =subcommandname=subcommandalias. Note that no | 
| |blanks may appear between the subcommand name and the | 
| |alias. j 

i i a 


Figure 10. Cards Used to Format a HELP Data Set 

All data cards, except the =subcommandname card, can contain 
additional information. If you include additional information on the 
cards, the control characters )S, )F, )X, and )0 must be followed by at 
least one blank, and the control character ))keyword by at least one 
blank or a left parenthesis. Use the left parenthesis when the keyword 
you are describing is followed by operands enclosed in parentheses. See 
Figure 9 for an example of this. 

The only restrictions on data cards are that columns 72-80 are 
reserved for sequence numbers, and column one must contain either a 
right parenthesis or an equal sign. 

For example, information concerning the sample command shewn below 
could be formatted for entry into the HELP data set (or your own private 
help data set) using the cards shown in Figure 11. The fictitious 
SAMPLE command could have the following format: 


SAMPLE 


positl [, (posit2)][KEYWDl [( posit3 ,posit4)11 
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The SAMPLE command has one subcommand, the EXAMPLE subcommand- 
fictitious EXAMPLE subcommand has the following format: 


EXAMPLE 


posit 10, positll 



[KEYWD13 (positl2 )] 


Figure 11 shows data cards that would present and format information 
about the SAMPLE command for inclusion in the HELP data set. 


flfl 


9SE3 
QSH 


BiE 



BBEBBBBBggflBSagga aBBaZflBBI BEBKggEaSBSMEEBBHHM 

BgBflB3BgBBa BBIBBIBggflaagBI 3gagiBaBIB3BBBB3BagB3 
3Bgiaa2Sa§IS2Z123B2EgBIB05ISaailMBBBBgaiill 






ggiiggaiZBasisagaazsgzsiaagKasisaaasEianE 



BBEB S3 B1ZB3SE gaBjzsaEBaBgMBggaasaaBB 

saszaBBnSasSSSgg^S 

SSBBaBBIIISBSSBE iasES 



SflSSESEDEIQEflSEBEBISBB 

HiSiSSIillSagBSDEBIBBi 

fluaasziBDaiBBaaBOBBiBgs 

BSaaBSBBIBEBiiSSglllHi 
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Message Handling 


TSO messages are divided into three classes: 

• Prompting messages 

• Mode messages 

• Informational messages 

Prompting messages are of the form ENTER... or REENTER..., and 
require a response from the user. Prompting messages should be 
initiated by the PARSE service routine, using the text supplied by the 

I command processor as the PROMPT operand of the IKJPOSIT, IKJTERM, 
IKJOPER, IKJRSVWD or IKJIDENT parse macro instructions. See the section 
headed "Using the PARSE Service routine (IKJPARS)" for a discussion of 
I the PROMPT operand on the these macro instructions. 

Mode messages are the READY message sent by the Terminal Monitor 
Program, and any other similar messages sent by command processors, such 
as the EDIT mode message sent by the EDIT command processor. They 
inform the user which command component is in control and let him know 
that the system is waiting for him to enter a new command or subcommand. 

Informational messages include all others; that is, any message which 
does not require an immediate response from the user. 

Prompting and Mode messages should be displayed using the PUTGET 
service routine. Informational messages should be displayed using the 
PUTLINE service routine. 


Message Levels 


Messages usually should have associated with them other messages that 
more fully explain the initial message. These messages, called second 
level messages, third level messages, and so forth, are displayed only 
if the user specifically requests them by entering a question mark "?". 

Prompting messages may have any number of additional levels. The 
second level is displayed if the user enters a question mark in response 
to the initial message. The last level is displayed if the user enters 
a question mark in response to the next to the last message. If the 
user at the terminal enters a question mark after all levels have been 
displayed, PUTGET displays the message "NO INFORMATION AVAILABLE". Pass 

I your second level prompting messages to the PARSE service routine by 
coding them as the HELP operand in the IKJPOSIT, IKJTERM, IKJOPER, 
IKJRSVWD and IKJIDENT parse macro instructions. 

An informational message can have only one second level message 
associated with it. Since many informational messages might be 
displayed at the terminal before a question mark is returned from the 
terminal, PUTLINE moves all second level informational messages to 
subpool 78 and chains them off the Environment Control Table. This 
chain exists from one PUTGET for a mode message to the next. In other 
words, whenever the user can enter a new command or subcommand, he can 
enter a question mark instead, requesting all the second level messages 
for informational messages issued during execution of the previous 
command or subcommand. If he does not enter a question mark, PUTGET 
deletes the second level messages and frees the main storage they 
occupy. 
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Mode messages cannot have second level messages, since a question 
mark entered in response to a mode message is defined as a request for 
the second levels of previous informational messages. Your program 
should request* all commands or subcommands by issuing a mode message 
with the PUTGET service routine so that second level informational 
messages may be properly handled. 


Effects of the Input Source on Message Processing 


Message handling is considerably affected if the input source designated 
by the input stack is an in-storage list rather than a terminal. See 
the explanation of the STACK macro instruction for a discussion of 
in-storage lists. In-storage lists may be either procedures or source 
lists. 

If a procedure is being executed, the PUTGET Service Routine does not 
display prompting messages, but returns an error code (12) in register 
15. If the PARSE Service Routine issued the PUTGET macro instruction, 
PARSE issues an informational message to the terminal, and returns an 
error code to its caller, (code 4). The command processor should reset 
the input stack and terminate. If a command processor issued the PUTGET 
macro instruction, the command processor should use the PUTLINE service 
routine to write an appropriate informational message to the terminal 
prior to terminating. 

If a source in-storage list is being processed, prompt messages are 
displayed to, and responses read from, the terminal by the PUTGET 
Service Routine. 

If the user at the terminal has specified the PAUSE operand on the 
PROFILE command, PUTGET issues a special message, "PAUSE", if all of 
these three conditions exist: 

(1) A mode message is to be written out. 

(2) Second level messages exist. 

(3) An in-storage list is being processed. 

The user may enter either a question mark or a null line. If he enters 
a question mark, the chain of second level messages is written to the 
terminal. If he enters a null line, control returns to the executing 
command processor. In either case, the next line from the in-storage 
list is returned to the command processor. 

A special situation arises if: an in-storage list is being 
processed,, second level messages are chained, and the user has specified 
NOPAUSE as an operand of the PROFILE command. Normally, if a subcommand 
encounters an error situation, it issues an information message and 
returns. The command processor then uses the PUTGET service routine to 
issue a mode message on the assumption that the user can take corrective 
action with other subcommands. When processing from an in-storage list, 
this is not true. If NOPAUSE was specified,, PUTGET merely returns an 
error code (12) to the calling routine. In most cases, the command 
processor should reset the input stack and terminate. If the message 
producing the second level message was purely informational and does not 
require corrective action, the command processor may set the ECTMSGF 
flag in the Environment Control Table to delete the second level 
message, and reissue tl^e PUTGET macro instruction to continue. 


46 Guide to Writing a TMP or a CP (Release 21.6) 



Attention Interruption Handling — The STAX Service Routine 


The STAX service routine creates the control blocks and queues necessary 
for the system to recognize and schedule user exits due to attention 
interruptions. Your Terminal Monitor Program, your command processors, 
or the problem program provide the address of an attention exit to the 
STAX service routine by issuing the STAX macro instruction. You should 
provide attention exit routines within the Terminal Monitor Program and 
any command processors that accept subcommands. 

When the attention exit routine is entered, all the subtasks of the 
interrupted task are stopped. If the subtasks must be dispatchable 
during attention exit processing, it is the user's responsibility to 
start the subtasks again by issuing the STATUS macro instruction. 

Note that when an attention interruption is entered from the 
terminal, the TGET and TPUT buffers are flushed. Any data contained in 
these buffers is lost. If the user then attempts to continue processing 
from the point of interruption, he may have lost an input or an output 
record, or an output message from the system. 


Specifying a Terminal Attention Exit - The STAX Macro Instruction 


The STAX macro instruction is used to specify the address of an 
attention exit routine that is to be given control asynchronously when 
the attention key is struck or when a simulated attention is specified. 
(See the STATTN macro instruction for a description of the simulated 
attention function.) 

The STAX macro instruction can also be used to cancel the last 
attention exit routine established by the task. To do this, specify the 
I STAX macro instruction without the exit address and DEFER operands. 

The STAX macro instruction is used only in a time sharing 
environment. It is ignored in a system that includes the time sharing 
option (TSO) if TSO is not active when the macro instruction is issued. 
In addition, attention exits can be established only for time sharing 
tasks operating in the foreground. 

Issue the STAX macro instruction to provide the information required 
by the STAX service routine. The STAX macro instruction has a list and 
an execute form. 

The List form of the STAX macro instruction (MF=L) generates a STAX 
Parameter List. The EXECUTE form of the STAX macro instruction 
(MF=E, (address)) completes or modifies that list and passes its address 
to the STAX service routine only if you specify either or both on exit 
address or deferral action. 

Figure 12 shows the format of the list and the execute forms of the 
STAX macro instruction; each of the operands is explained following the 
figure. Appendix B describes the notation used to define macro 
instructions. 


Attention Interruption Handling - the STAX Service Routine 47 




Figure 12. The STAX Macro Instruction — List and Execute Forms 


exit address 

Specify the entry point of the routine to be given control when an 
attention interruption is received. You must specify the exit 
address in both the list and the execute forms of the STAX macro 
instruction when you are establishing an attention interruption 
handling exit. 

You need not specify an exit address if you are using the DEFER 
operand as long as you code no other operands (except the MF 
operand). If you exclude the exit address and the DEFER operand 
and code other operands, the STAX service routine merely cancels 
the previous attention exit established by the task issuing this 
STAX macro instruction. If you exclude the exit address and code 
the DEFER operand, with or without other operands, only the 
deferral status is changed. 

OBUF=(output buffer address,output buffer size) 

Output buffer address - Supply the address of a buffer you have 
obtained and initiated with the message to be put out to the 
terminal user who entered the attention interruption. This message 
may identify the exit routine and request information from the 
terminal user. It is sent to the terminal before the attention 
exit routine is given control. 

Output buffer size - Indicate the number of characters in the 
output buffer. The size may range from 0 to 32,767 (2 iS -l 
inclusive). 

IBUF=(input buffer address,input buffer size) 

Input buffer address - Supply the address of a buffer you have 
obtained to receive responses from the terminal user. The 
attention exit routine is not given control until the STAX service 
routine has placed the terminal user's reply into this buffer. 

Input buffer size - Indicate the number of bytes you have provided 
as an input buffer. The size may range from 0 to 32,767 (2 15 -1 
inclusive). 

USADDR=(user address) 

The user address is a pointer to any information you want passed to 
your attention handling exit routine when it is given control. 


48 Guide to Writing a TMP or a CP (Release 21.6) 








RE PLACE=YES or NO 

YES indicates that the attention exit specified by this STAX macro 
instruction replaces any attention exit specified by a STAX macro 
instruction previously issued by this task. YES is the default 
value. REPLACE implies add, if no previous attention exit has been 
established. 

NO indicates that this attention exit is an additional exit to any 
that have been previously established for this task. 

DEFER=YES or NO 

The DEFER operand is optional. If the DEFER operand is coded in 
the STAX macro instruction, the option you request (YES or NO) 
applies to all tasks within the task chain in which the macro 
instruction was issued. Any task may issue the STAX macro 
instruction to specify DEFER=YES or NO; the issuing task need not 
itself have provided an attention exit routine. If the DEFER 
operand is not coded in the macro instruction, no action is taken 
by the STAX service routine regarding the deferral of attention 
exits. 

YES indicates that any attention interruptions received are to be 
queued and are not to be processed until another STAX macro 
instruction is executed specifying DEFER=N0, or until the program 
that issued the STAX with the DEFER=YES terminates. 

NO indicates that the defer option is being cancelled. Any 
attention interruptions received while the defer option was in 
effect are to be processed in a first-in, first-out manner. If the 
DEFER operand is omitted, the control program leaves the deferral 
status unchanged. 

Be aware that if a program issues a STAX macro instruction 
specifying DEFER=YES, it can get into a situation where an 
attention interruption cannot be received from the terminal. If 
your program enters a loop or an unending wait before it has issued 
a STAX macro instruction specifying DEFER=N0, you cannot regain 
control at the terminal by entering an attention interruption. 

You need not specify an exit address in a STAX macro instruction 
issued only to change deferral status. Note, however, that a STAX 
macro instruction entered without an exit address is considered to 
be a STAX cancel if any operands are included other than DEFER and 
MF. 


When control is passed to another routine with an XCTL macro 
instruction, the routine receiving control assumes the deferral 
status of the routine that issued the XCTL macro instruction. 

When control is passed to another routine with a LOAD or CALL macro 
instruction, the routine receiving control also receives the 
deferral status of the routine that passed control. If the routine 
receiving control changes deferral status, it remains changed when 
control is returned. 

When control is passed to another routine with a LINK macro 
instruction, the routine receiving control maintains its own 
deferral status: It does not receive a deferral status when it 
receives control nor does it return a deferral status when it 
returns control. 


MF=L 

This specifies the list form of the STAX macro instruction. It 
generates a STAX Parameter List. 
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MF= (E,(address)) 

This specifies the execute form of the STAX macro instruction. It 
completes or modifies the STAX Parameter List and passes the 
address of the Parameter List to the STAX service routine. Place 
the address of the STAX Parameter list (the address of the list 
form of the STAX macro instruction) into a register and specify 
that register number within parentheses. 

You can place each of the required address and size parameters into 
registers and specify those registers, within parentheses, in the STAX 
macro instruction. Figure 13 shows how an execute form of the STAX 
macro instruction may look if you load all the required parameters into 
registers. 

If an attention exit is specified in the list form, but no attention 
exit is specified in the execute form, then this is considered a cancel 
operation. 


f” STAX (2),IBUF=((3),(4)),OBUF=((5),(6)),USADDR=(7),MF=(E,(1)) ] 

L-J 


Figure 13. Using Registers in the STAX Macro Instruction 
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The STAX Parameter List 


When the list form of the STAX macro instruction expands, it builds a 
five word STAX Parameter List. The list form of the macro instruction 
initializes this STAX Parameter List according to the operands you have 
coded. 

The execute form of the STAX macro instruction modifies the STAX 
Parameter List and passes its address to the STAX service routine. 
Figure 14 describes the contents of the STAX Parameter List. 


r- t 

Number of 
Bytes 


Field 


STXEXIT 


STXISIZ 


Contents or Meaning 


The address of the attention exit routine to 
receive control in response to an attention 
interruption. This is the address you 
supplied as the exit address operand on the 
STAX macro instruction. 


Contains a binary number representing the 
size of the input buffer you provided as the 
IBUF operand on the STAX macro instruction. 
The maximum buffer size is 4095 bytes. 

- 

Contains a binary number representing the 
size of the output buffer you provided as the 
OBUF operand on the STAX macro instruction. 
The maximum buffer size is 4095 bytes. 


STXOSIZ 


-^ 

Contains the address of the output buffer you 
provided as the OBUF operand on the STAX 
macro instruction. 


STXOBUF 




STXIBUF 


Contains the address of the input buffer you 
provided as the IBUF operand on the STAX 
macro instruction. 


H 


STXOPTS 

. 0 . . 
. 1 .. .. 
.. 1 . .. 

... 1 • . 


x. 


xxxx 


STAX option flags. 

REPLACE=YES 

REPLACE=NO 

Defer attention interruption processing, that 
is DEFER=YES. 

Cancel the deferral of attention interruption 
processing, that is DEFER=NO. 

Reserved bits. 


-+ 


STXUSER 


Contains the address of the parameters you 
want passed to your attention handling exit 
routine when it is given control. This is 
the address you supplied as the USADDR 
operand on the STAX macro instruction. 


-f 


Figure 14. The STAX Parameter List 
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Coding Example of the STAX Macro Instruction 


The coding example shown in Figure 15 uses the list and the execute 
forms of the STAX macro instruction to set up an attention handling 
exit. The OBUF operand provides a message to be written to the terminal 
when the attention interruption is received, and the IBUF operand 
provides space for an input buffer. This example does not code the 
REPLACE operand in the macro instruction; YES is the default value. The 
attention handling exit established by this execution of the STAX macro 
instruction replaces the previous attention handling exit established 
for this task. 


BHHBSHMaElBlBMBBMBaaMBBBliBlMm MBiBMDilBlEBBBBllBlIH 



mmmmmwmmm 



IB 



wmm mBwmwmmmmmmwm 

IIIIIIIIIIIIIIIIIIIIIIIIIIIIIQ 



xwwmm mmmmmmm i a iiiiDsiBiiiiii 



iiiiiiiiiiiiii 


Bssssasssssssam 
I Bi i 

SBBBSSIIIIBS 59 S 5 SBBS 5 I 959 H 



BSSSSHBSSSSSSSSH 
BSSSSBBSBSSBSHHi 


wummmmMmmmmmn 


liiiiiBi 


mmmm 



HUfliiiiifliiifliiiimaaiDasan&QQsaisasGiHflm 



Figure 15. Coding Example — STAX Macro Instruction 
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Return Codes From the STAX Service Routine 


When the STAX service routine returns control to the program that issued 
the STAX macro instruction, register 15 contains one of the following 
return codes s 

CODE MEANING 

0 The STAX service routine successfully completed the function 

you requested. That is, it queued the attention exit you 
passed it, or it cancelled an existing attention exit. 

4 Deferral of attention exits has already been requested and 

is presently in effect. Any other operands you specified in 
the STAX macro instruction have been processed successfully. 

8 Invalid parameter passed to the STAX service routine; your 

STAX macro instruction was ignored. 
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Dynamic Allocation of Data Sets -- The Dynamic Allocation Interface 
Routine (DAIR) 


Dynamic Allocation routines allocate, free, concatenate, and 
deconcatenate data sets dynamically; that is, during problem program 
execution. With the Time Sharing Option, dynamic allocation permits the 
Terminal Monitor Program, Command Processors, and other problem programs 
executing in the foreground region to allocate data sets after LOGON and 
free them before LOGOFF. 

For a complete discussion of Dynamic Allocation, see the TSO Terminal 
Monitor Program and Service Routines PLM. 

The Dynamic Allocation routines may be accessed from a TSO foreground 
region only through the Dynamic Allocation Interface Routine (DAIR). In 
general, DAIR obtains information about a data set and, if necessary, 
invokes Dynamic Allocation routines to perform the requested function. 

You can use DAIR to perform the following functions: 

• Obtain the current status of a data set. 

• Allocate a data set (See note). 

• Free a data set. 

• Concatenate data sets. 

• Deconcatenate data sets. 

• Build a list of attributes (DCB parameters) to be assigned to data 
sets. 

• Delete a list of attributes. 

Note : 

If you wish to allocate a data set to a direct access device, the 

device must be available. To be available, the device must be: 

• On line 

• Ready 

• Shareable. 


Further conditions: 

• An offline or unload condition must not be pending. 

• There must be no outstanding MOUNT message. 

• The volume attributes must have been defined. 
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Using DAIR 


Enter the DAIR service routine with a LINK macro instruction to entry 
point IKJEFDOO in load module IKJEFDOO. The control block structure 
required by the DAIR service routine is shown in Figure 16. Note that 
the DAIR Parameter Block (DAPB) is a variable-size block; the block size 
depends upon the function requested by the calling routine. That 
function is indicated to the DAIR service routine by the code in the 
first two bytes of the DAIR Parameter Block. 



DAPB 


0 

Entry Code 



Figure 16. Control Blocks Passed to DAIR 
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THE DAIR PARAMETER LIST (DAPL) 


At: entry to DAIR, register 1 must point to a DAIR Parameter List that 
you have built. Figure 17 shows the format of the DAPL. The addresses 
of the user profile table, environment control table, and protected step 
control block may be obtained from the command processor parameter list 
(CPPL) that the TMP passes to your command processor (See Figure 33). 
Additional information on the address and creation of the user profile 
table, environment control table, and protected step control block is 
shown in Figure 5 (the Test Parameter List). 


r --- T 

Number of 
Bytes 


Field 


jContents or Meaning 


DAPLUPT 


|The address of the User Profile Table. 


4 

4 


DAPLECT 

DAPLECB 


|The address of the Environment Control Table. 


|The address of the calling program's Event 
|Control Block. The ECB is one word of 
|storage declared and initialized to zero by 
|the calling routine. 

-+- 


DAPLPSCB jThe address of the Protected Step Control 
|Block. 


DAPLDAPB 


| The address of the DAIR Parameter Block, 
| created by the calling routine. 


Figure 17. Format of the DAIR Parameter List (DAPL) 
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THE DAIR PARAMETER BLOCK (DAPB) 

The fifth word of the DAIR Parameter List must contain a pointer to a 
DAIR Parameter Block built by the calling routine* 

It is a variable-size parameter block that contains* in the first two 
bytes* an entry code that defines the operation requested by the calling 
routine* The remaining bytes contain other information required by DAIR 
to perform the requested function. Figure 18 is a list of the DAIR 
entry codes and the functions requested by those codes. 


r 


Entry 

Code 


X - 00 f 

X f 04* 

X f 08' 
X* 0C 1 
X^O 1 

X *^ 1 

X f 18 * 
X'lC* 

x'2tr 
X f 28 1 
X^C* 
X*30 f 
X 1 34 * 


Function Performed by DAIR 


Search the DSE for information about a data set by DDNAME or 
DSNAME. 

Search the DSE for information about a data set by DSNAME. If 
not found, search the system catalog. 

Allocate a data set by DSNAME. 

Concatenate data sets by DDNAME. 

Deconcatenate data sets by DDNAME. 

Search the system catalog for all qualifiers for a DSNAME. 

(The DSNAME alone represents an unqualified index entry.) 

Free a data set. 

Allocate a DDNAME to a terminal. 

Allocate a data set by DDNAME or DSNAME. 

Perform a list of operations. 

Mark data sets as not in use. 

Allocate a SYSOUT data set. 

Build or delete an attribute control block (ATRCB)• 


Figure 18. DAIR Entry Codes and Their Functions 


The DAIR Parameter Blocks have the formats shown in the following 
tables. The formats of the blocks depend upon the function requested by 
the calling routine. The function is indicated by the entry code in the 
first two bytes of the DAIR Parameter Block. 
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Code X'OQ' - Search the DSE for a Data Set Name 


Build the DAIR Parameter Block shewn in Figure 19 to request that DAIR 
search the Data Set Extension for a fully qualified data set name. 


Number of 
Bytes 


Field 


Contents or Meaning 


-H 


l— 


DAOOCD 


Entry code X'0000* 


I— 


DAOOFLG 


Byte 1 
0000 .... 

Byte 2 
0000 0000 


A flag field set by DAIR before returning to j 
the calling routine. The flags have the | 

following meaning: 

Reserved. Set to zero. 

DSNAME or DDNAME is permanently allocated. 
DDNAME is a DYNAM. 

The DSNAME is currently allocated; it appears 
in the DSE. 

The DDNAME is currently allocated to the 
terminal. 

Reserved. Set to zero. 


DA00PDSN 


DA00DDN 


Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following format: 

The first two bytes contain the length, in 
bytes of the DSNAME; 

The next 44 bytes contain the DSNAME, left 
justified, and padded to the right with 
blanks. 

Contains the DDNAME for the requested data 
set. If a DSNAME is present, the DAIR 
service routine ignores the contents of this 
field. 


DA00CTL 
00.0 0000 
. .1 . 


A flag field: 

Reserved bits. Set to zero. 
Prefix userid to DSNAME. 


2 

1 


Reserved bytes; set these bytes to zero. 


DA00DSO 


1 ... .... 

la. .... 

.1 . 

..0 00 .. 
... . . 1 . 

... ... 1 


A flag field: These flags describe the 
organization of the data. They are returned 
to the calling routine by the DAIR service 
routine. 

Indexed Sequential (IS). 

Physical Sequential (PS). 

Direct Organization (DO). 

Reserved bits. Set to zero. 

Partitioned Organization (PO). 

Unmoveable. 


Figure 19. DAIR Parameter Block — Entry Code X'OO* 

After DAIR searches the Data Set Entry for the fully qualified data 
set name, register 15 contains one of the following DAIR return codes; 

0 , 4 


See the topic "Return Codes from DAIR" for return code meanings. 
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Code X* 04 


Search the DSE and the System Catalog for Data Set Name 


Build the DAIR Parameter Block shown in Figure 20 to request that DAIR 
search the Data Set Extension for a fully qualified data set name. If 
the data set is not found in the DSE, DAIR also searches the system 
catalog. 


r i 

Number of 
Bytes 

.. ^ 

i 

Field |Contents or Meaning 

|_ - r ._ . j -| 

2 

DA04CD |Entry code X'0004'. 

I _ _ j 

2 

r t 1 

DA04FLG |A flag field set by DAIR before returning to 

jthe calling routine. The flags have the 
following meanings 

Byte 1 | 

0000 0..0 [Reserved bits. Set to zero. 

.... .1.. j DAIR found the DSNAME in the catalog. 

.... ..1. jThe DSNAME is currently allocated in the Data 
jset Extension. 

Byte 2 j 

0000 0000 |Reserved. Set to zero. 

L .. 1 .. , . ..... 

r 

2 

T 

|Reserved bytes. Set to zero, 
j 

2 

DA04CTRC | These two bytes will contain an error code 

j from the catalog management routines if an 
j error was encountered by catalog management. 

.. ....j .. .. .... .... __ ... .. . ... . . 

4 

DA04PDSN jPlace in this field the address of the DSNAME 

jbuffer. The DSNAME buffer is a 46-byte field 
jwith the following formats 

|The first two bytes contain the length, in 
(bytes, of the DSNAME; 

|The next 44 bytes contain the DSNAME, left 
j justified, and padded to the right with 

|blanks. 

... _ 

r ” " 

1 

DA04CTL |A flag field: 

00.0 0000 jReserved bits. Set to zero. 

..1.|Prefix userid to DSNAME. 

I i 

r 

2 

r t — — 

|Reserved bytes; set these bytes to zero. 

1 

L J 

T 1 

DA04DSO | A flag field. These flags are set by the 

(DAIR Service routine; they describe the 
(organization of the data set to the calling 
|routine. These flags are returned only if 
jthe data set is currently allocated in the 
j DSE. 

1. jIndexed Sequential (IS). 

.1. [physical Sequential (PS). 

..1.(Direct Organization (DO). 

...0 00.. [Reserved bits. Set to zero. 

.... ..1. (Partitioned Organization (PO). 

.1 j Unmoveable. 

LX J 


Figure 20. DAIR Parameter Block — Entry Code X , 04 f 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0 f 4 # 8 

See the topic "Return Codes from DAIR" for return code meanings. 
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Build the DAIR Parameter Block shown in Figure 21 to request that DAIR 
allocate a data set. The exact action taken by DAIR depends upon the 
presence of the optional fields and the setting of bits in the control 
byte. 

If the data set is new and you specify DSNAME, (NEW, CATLG) DAIR 
catalogs the data set upon successful allocation. If the catalog 
attempt is unsuccessful, DAIR frees the data set. 

If the proper indices are not present, the catalog macro CATBX 
attempts to build indices for DAIR. 

DAIR searches the Data Set Extension in a manner that depends upon 
the information you supply in the DAIR Parameter Block. DAIR may search 
on DSNAME alone, DSNAME and DDNAME if both are specified, DDNAME alone 
if no DSNAME is specified, or DAIR may search for any available entry. 

If DAIR searches for an available entry in the DSE, the order of 
selection is: 

1. A DYNAM entry. 

2. A data set that is currently allocated but not in use and not 
permanently allocated. 

3. A concatenated data set not in use and not permanently allocated. 

If neither of the above types of DSE entries can be found, allocation 
cannot take place. If an entry can be found from number 2 (above) DAIR 
frees the entry and uses it for the requested allocation. If DAIR can 
find an entry from number 3 (above), it deconcatenates, then frees the 
data set. 

To allocate a utility data set use DAIR code X'08' and use a DSNAME 
of the form £name. If the Sname is found allocated in the Data Set 
Extension, that data set is used. If the £name is not found, DAIR 
attempts to allocate a data set. 

To supply DCB information, provide the name of an attribute list that 
has been defined previously by a X^U* entry into DAIR. 

The DAIR Parameter Block required for entry code X f 08' has the 
following format: 


Figure 21. DAIR Parameter Block — Entry Code X'OS 1 (Part 1 of 3) 


Number of| 

Bytes |FieId 


Contents or Meaning 


IDA08CD 


Entry code X^OOS*. 


| DA08FLG 


| Byte 1 

| 1 . 


| .000 0000 

| Byte 2 


A flag field set by DAIR before returning to the 
calling routine. The flags have the following 
meaning: 

The data set is allocated but a secondary error 
occurred. Register 15 contains an error code. 
Reserved bits. Set to zero. 

Reserved. Set to zero. 


|DA08DARC 


This field contains the error code, if any, 
returned from the Dynamic Allocation routines. 
(See "Return Codes from Dynamic Allocation.") 


I DA08CTRC 


This field contains the error code, if any, 
returned from Catalog Management Routines. 
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Number of 
Bytes 


Field 


Contents or Meaning 


DA08PDSN 


Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following format: 

The first two bytes contain the length, in 
bytes, of the DSNAME; the next 44 bytes 
contain the DSNAME, left justified and padded 
to the right with blanks. 


DA08DDN 


This field contains the DDNAME for the data 
set. If a specific DDNAME is not required, 
fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the 
data is allocated. 


DA08UNIT 


Unit name desired. If name blank, defaults 
to PSCBGPNM contents. If name is less than 
eight bytes long, pad it with blanks at 
right. 


DA08SER 


Serial number desired. Only the first six 
bytes are significant. If the serial number 
is less than six bytes, it must be padded to 
the right with blanks. If the serial number 
is omitted, the entire field must contain 
blanks. 


DA08BLK 


Block size requested. This figure represents 
the average record length desired. 


DA08PQTY 


Primary space quantity desired. The high 
order byte must be set to zero; the low order 
three bytes should contain the space quantity 
required. If the quantity is omitted, the 
entire field must be set to zero. 


DA08SQTY 


Secondary space quantity desired. The high 
order byte must be set to zero; the low order 
three bytes should contain the secondary 
space quantity required. If the quantity is 
omitted, the entire field must be set to 


DA08DQTY 


Directory quantity required. The high order 
byte must be set to zero; the low order three 
bytes contain the number of Directory blocks 
desired. If the quantity is omitted,, the 
entire field must be set to zero. 


DA08MNM 


Contains a member name of a partitioned data 
set. If the name has less than eight 
characters, pad it to the right with blanks. 
If the name is omitted, the entire field must 
contain blanks. 


DAO 8 PS WD 


Contains the password for the data set. If 
the password has less than eight characters, 
pad it to the right with blanks. If the 
password is omitted, the entire field must 
contain blanks. 


Figure 21. DAIR Parameter Block — Entry Code X'OS* (Part 2 of 3) 
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r i 

Number of 
Bytes 

. . 

r t i 

I 1 

Field (Contents or Meaning | 

I .... .. ... ... _.... ..... ... .. ... ... i 

r 

1 

_ ... . 

- — 

T 1 

DAO8DSPI |Flag byte. Set the following bits to indicate | 

| the status of the data set: | 

0000 ....]Reserved. Set these bits to zero. | 

-1_| SHR | 

.1..|NEW | 

. 1.|MOD j 

_ J J 

1 

. . ... 

- — 

T t 

DA08DPS2 (Flag byte. Set the following bits to indicate ( 

|the normal disposition of the data set: | 

0000 ....(Reserved bits. Set them to zero. | 

- 1...|KEEP | 

.1.. (DELETE | 

. 1.|CATLG | 

.11UNCATLG | 

1 

DA08DPS3 |Flag byte. Set the following bits to indicate | 

(the abnormal disposition of the data set: | 

0000 ....(Reserved bits. Set them to zero. | 

.... 1...|KEEP j 

.1..|DELETE | 

.1. (CATLG j 

1 i 

1 

n~ t 1 

DA08CTL |Flag byte. These flags indicate to the DAIR | 

|service routine what operations are to be j 

(performed: | 

xx.(Indicate the type of units desired for the space | 

(parameters, as follows: | 

01.. ....|Units are in average block length. | 

10.. ....|Units are in tracks (TRKS)• j 

11.(Units are in cylinders (CYLS). | 

. .1.| Prefix userid to DSNAME. j 

...1 ..•.|RLSE is desired. | 

.... l...|The data set is to be permanently allocated; it | 
jis not to be freed until specifically requested, j 
.... . 1.. |A DUMMY data set is desired | 

.1.(Attribute list name supplied. j 

L _ 1 _ I 

3 

i 

T 1 

(Reserved bytes; set them to zero. | 

.i ..... . a 

r 

1 

j 

T 1 

DA08DSO |A flag field. These flags are set by the DAIR | 

|service routine; they describe the organization j 
jof the data set to the calling routine. j 

.1.(Physical Sequential (PS). | 

..1.(Direct Organization (DO). j 

...0 00..(Reserved bits. Set to zero. j 

.... ..1.|Partitioned Organization (PO). j 

L | __ 1 

r — 1 

8 

L 

r 1 1 

DA08ALN (Attribute list name. j 

LX J 


Figure 21- DAIR Parameter Block — Entry Code X'08 1 (Part 3 of 3) 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 8, 12, 16, 20, 28, 32, 44 

See the topic "Return Codes from DAIR" for return code meanings. 


62 Guide to Writing a TMP or a CP (Release 21.6) 

























Code X'OC* - Concatenate the Specified DDNAMES 


Build the DAIR Parameter Block shown in Figure 22 to request that DAIR 
concatenate data sets. Entry code X*0C f indicates that the DDNAMES 
listed in the DAIR Parameter Block are to be concatenated in the order 
in which they appear. All data sets listed by DDNAME in the DAIR 
Parameter Block must be currently allocated. 


DAIR marks the DSE entry for each member it concatenates. This is 
done in case a subsequent request for allocation of a data set requests 
a member of the group. If the group was concatenated by DAIR, DAIR 
deconcatenates the group and proceeds with the requested allocation. If 
the group was concatenated at LOGON, DAIR makes a duplicate entry for 
the data set; that is f there will be two entries in the DSE for the same 
data set. 


r i 

Number of 
Bytes 
l 

r i 

Field 

r i 

Contents or Meaning j 

j 

- 1 

2 

. 

DAOCCD 

r 1 

Entry code X'OOOC* | 

i 

2 

L J 

DAOCFLG 

r 1 

Reserved. Set this field to zero. | 

j 

1 1 

2 

DAOCDARC 

i 

This field contains the error code, if any, | 
returned from the Dynamic Allocation | 

routines. (See "Return Codes from Dynamic | 

Allocation.") | 

i 

r 1 

2 


r 1 

Reserved field . Set this field to zero. | 

l* . *1 

2 

DAOCNUMB 

r — 1 
Place in this field the number of data sets | 
to be concatenated. j 

2 

r — 1 

r ■ ““"“1 

Reserved. Set this field to zero. | 

8 

l J 

r 1 

DAOCDDN 

L J 

r - 1 

Place in this field the DDNAME of the first | 
data set to be concatenated. This field is j 
repeated for each DDNAME to be concatenated, j 

L J 


Figure 22. DAIR Parameter Block — Entry Code X f 0C* 

After attempting the requested function, DAIR returns one of the 
following codes in register 15. 

0, 4, 12 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X g 10 


Deconcatenate the Indicated DDNAME 


Build the DAIR Parameter Block shown in Figure 23 to request that DAIR 
deconcatenate a data set. Entry code X'10* indicates that the DDNAME 
specified within the DAIR Parameter Block has been previously 
concatenated and is now to be deconcatenated. 


r - T - 

Number of | 

Bytes I Field 


h 


|Contents or Meaning 


j DAI0CD 

4 - 

I DA10FLG 


jEntry code X'0010' 

|Reserved. Set this field to zero. 


-^ 


I— 


DA10DARC |This field contains the error code, if any, 
|returned from the Dynamic Allocation 
jroutines. (See "Return Codes from Dynamic 
j Allocation.") 


—^ 


j Reserved field, set this field to zero. 


1 

--L- 


DA10DDN |Place in this field the DDNAME of the data 
|set to be deconcatenated. 


Figure 23. DAIR Parameter Block — Entry Code X^O 1 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 


0, 4, 12 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X'14' - Return Qualifiers for the Specified PSNAME 


Build the DAIR Parameter Block shown in Figure 24 to request that DAIR 
return all qualifiers for the DSNAME specified• 


You must also provide the return area pointed to by the third word of 
the DAIR Parameter Block• If the area you provide is larger than needed 
for all returned information, the remaining bytes in the area are set to 
zero by DAIR. If the area is smaller than required, it is filled to its 
limit, and the return code specifies this condition. 


Number of 
Bytes 


Field 


Contents or Meaning 


DA14CD 

DA14FLG 

DA14PDSN 


Entry code X'0014'. 
+- 


Reserved. Set this field to zero. 


Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following formats 

The first two bytes contain the length, in 
bytes, of the DSNAME; 

The next 44 bytes contain the DSNAME, left 
justified and padded to the right with 
blanks. DSNAME alone represents an 
unqualified index entry. 




1 


DAI4 PRET 


Place in this field the address of the return 
area in which DAIR is to place the qualifiers 
found for the DSNAME. Place the length of 
the return area in the first two bytes of the 
return area. Set the next two bytes in the 
return area to zero. DAIR returns each of 
the qualifiers it finds in two fullwords of 
storage beginning at the first word (offset 
0) within the return area. 


DA14CTL 

Byte 1 
00.0 0000 


A flag field: 


Reserved bits; set them to zero. 
Prefix userid to DSNAME. 




-H 


I 

_X- 


| Reserved bytes. Set this field to zero. 
_x_____ 


Figure 24. DAIR Parameter Block — Entry Code X f 14* 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 36, 40 

See the topic "Return Codes from DAIR* for return code meanings. 
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Code X 8 18 * - Free the Specified Data set 


Build the DAIR Parameter Block shown in Figure 25 to request that DAIR 
free a data set. Entry code X*18 1 indicates that the data set name 
represented by DSNAME is to be freed. If no DSNAME is given, the data 
set associated with the DDNAME is freed. If both DDNAME and DSNAME are 
given, DAIR ignores the DDNAME. 


If the specified DSNAME appears several times in the Data Set 
Extension, all such entries are freed. 


r t 

Number of | 

Bytes I Field 

. ._......j... 

r i 

Contents or Meaning 

2 | DA18CD 

j 

Entry code X'OOIS*. 

2 j DA18FLG 

1 

1 

1 

| Byte 1 

| 1. 

1 

1 

| .000 0000 

1 

| Byte 2 

j , 

A flag field set by DAIR before returning to 
the calling routine. The flags have the 
following meanings: 

The data set is freed but a secondary error 
occurred. Register 15 contains an error 
code. 

Reserved bits. Set to zero. 

Reserved. Set to zero. 

..... . ... _ ... 

2 | DA18DARC 

1 

1 

1 

j | 

This field contains the error code, if any, 
returned from the Dynamic Allocation 
routines. (See "Return Codes from Dynamic 

Allocation.") 

__ _ . .. 

2 | DA18CTRC 

1 

-j. ,| 

This field contains the error code, if any, 
returned from Catalog Management routines. 

4 i DA18PDSN 

1 

1 

1 

1 

1 

1 

1 

-J- ..j 

Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following format: 

The first two bytes contain the length, in 
bytes, of the DSNAME; 

The next 44 bytes contain the DSNAME, left 
justified and padded to the right with 
blanks. 

8 | DA18DDN 

1 

j -| 

Place in this field the DDNAME of the data 
set to be freed, or zeros. 

8 | DA18MNM 

1 

1 

1 

1 

- -L . _J 

Contains the member name of a partitioned 
data set. If the name has less than eight 
characters, pad it to the right with blanks. 

If the name is omitted, the entire field must 
contain blanks. 

L . _. . ... 

T 1 

2 | DAI8SCLS 

1 

1 

L X J 

SYSOUT class. An alphabetic or numeric 
character. If SYSOUT is not specified, this 
field must contain blanks. 


Figure 25. DAIR Parameter Block — Entry Code X'IS 1 (Part 1 of 2) 
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Number of 
Bytes 


Field 


Contents or Meaning 


DA18DPS2 


0000 .... 

.... .. 1 . 

.... ...1 


Flag byte. Set the following bits to 
indicate the normal disposition of the data 
sets 

Reserved bits. Set them to zero. 

KEEP 
DELETE 
CAT LG 
UNCATLG 


DA18CTL 


00 .. 0000 


Flag byte. These flags indicate to the DAIR 
service routine what operations are to be 
performed: 

Prefix userid to DSNAME. 

Reserved bits; set them to zero. 

If this bit is on, permanently allocated data 
sets are unallocated and marked "not in use." 
If the bit is off, the data set will be 
marked "not in use," if it is permanently 
allocated. 


DA18JBNM 


Place the jobname for enqueuing SYSOUT data 
sets in this field. If the jobname is 
omitted, DAIR takes the jobname from the 
TIOT. 


Figure 25. DAIR Parameter Block — Entry Code X f 18* (Part 2 of 2) 


After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 8, 12, 24, 28 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X*1C' - Allocate the Specified DDNAME to the Terminal 


Build the DAIR Parameter Block shown in Figure 26 to request that DAIR 
allocate a DDNAME to the terminal. Entry code X*lc' indicates that the 
DDNAME specified within the DAIR Parameter Block is to be allocated to 
the terminal. If the DDNAME field is left blank, DAIR returns the 
allocated DDNAME in that field. To supply DCB information, provide the 
name of an attribute list that has been defined previously by a X f 34 t 
entry into DAIR. 


Number of | 

Bytes | Field 

i i 

1 

Contents or Meaning | 

2 | DA1CCD 

j j 

Entry code X'OOIC* | 

2 | DA1CFLG 

j ,| 

- 1 

Reserved field; set it to zero. | 

L_... . .. . ... .. 1 

2 { DA1CDARC 

1 

1 

1 

r ' - —— 1 

This field contains the error code, if any, | 

returned from the Dynamic Allocation j 

routines. (See "Return Codes from Dynamic j 

Allocation.") j 

|_ .. . . . ..- . _... . ... _ __ . .j 

--- f 1 

1 1 

Reserved field; set it to zero. | 

.-... - . . .... j 

1 | DA1CCTL 

| .... 1... 

1 

1 

| _ ..1. 

j xxxx «x.x 

Control byte: j 
The data set is to be permanently allocated; | 
it is not to be freed until specifically j 
requested. j 
Attribute list name supplied. j 
Each x represents a reserved bit. | 

— ~ T 1 

8 | DA1CDDN 

1 

Place in this field the DDNAME for the data | 
set to be allocated to the terminal. j 

8 i DA1CALN i 

Attribute list name. j 


L_X_X_J 

Figure 26. DAIR Parameter Block — Entry Code X*1C* 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 12, 16, 20, 28 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X*24* - Allocate a Data Set by DDNAME 


Build the DAIR Parameter Block shown in Figure 27 to request that DAIR 
allocate a data set by DDNAME• 

DAIR searches the Data Set Extension using as an argument the DDNAME 
you specify in the DAIR Parameter Block. 

If DAIR locates the DDNAME you specify and a DSNAME is currently 
associated with it,, the associated DSNAME is allocated overriding the 
DSNAME pointed to by third word of your DAIR Parameter Block. DAIR 
replaces the DSNAME in your DSNAME buffer with the DSNAME found 
associated with the DDNAME you specified* and updates the buffer length 
field. The DDNAME must also be permanently allocated when found or 
allocation will be by DSNAME with a generated DDNAME. 

If there is no DSNAME associated with the DDNAME you specified, it is 
DYNAM or does not exist. DAIR searches the DSE using the DSNAME you 
specify as an argument. If DAIR cannot allocate by DDNAME, it will give 
control to code X*08 f to allocate by DSNAME and will generate a new 
DDNAME. 


r-r 

Number of 
Bytes 


Field 


Contents or Meaning 


DA24CD 


Entry code X i 0024'. 


DA24FLG 


Byte 1 

1 ... .... 


.... 1 ..• 

.000 .000 

Byte 2 


A flag field set by DAIR before returning to 
the calling routine. The flags have the 
following meaning: 

The data set is allocated but a secondary 
error occurred. Register 15 contains an 
error code. 

DDNAME requested is allocated as DUMMY. 
Reserved bits. Set to zero. 

Reserved. Set to zero. 


+ - 


+- 


-H 


DA24DARC 


This field contains the error code, if any, 
returned from the Dynamic Allocation 
routines. (See "Return Codes from Dynamic 
Allocation.") 


DA24CTRC 


This field contains the error code, if any,, 
returned from Catalog Management Routines. 


DA24PDSN 


Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following format: 

The first two bytes contain the length, in 
bytes, of the DSNAME; 

The next 44 bytes contain the DSNAME, left 
justified and padded to the right with 
blanks. 




H 


DA24DDN 


Place here the DDNAME for the data set to be 
allocated. This DDNAME is required. 


DA24UNIT 


Unit name desired. If blank, defaults to 
PSCBGPNM contents. If the unit name is less 
than eight bytes, pad it to the right with 
blanks. 


Figure 27. DAIR Parameter Block — Entry Code X'24 f (Part 1 of 3) 
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r 1 

Number of 
Bytes 

Field j Contents or Meaning 

i . ..... .. .. _ ....... 

8 

. 

T T 

DA24SER |Serial number desired. Only the first six 

(bytes are significant. If the serial number 
|is less than six bytes, it must be padded to 
|the right with blanks. If the serial number 
(is omitted, the entire field must contain 
|blanks. 

4 

r T 1 

DA24BLK (Block size requested. This figure represents 

(the average record length desired. 

r 1 

4 

DA24PQTY jPrimary space quantity desired. The high 

jorder byte must be set to zero; the low order 
(three bytes should contain the space quantity 
(required. If the quantity is omitted, the 
|entire field must be set to zero. 

i . 

4 

. 

T 

DA24SQTY (Secondary space quantity desired. The high 

(order byte must be set to zero; the low order 
|three bytes should contain the secondary 
j space quantity required. If the quantity is 
(omitted, the entire field must be set to 
j zero. 

i ...____ ________ __ 

4 

....... . 

DA24DQTY (Directory quantity required. The high order 

|byte must be set to zero; the low order three 
|bytes contain the number of Directory blocks 
|desired. If the quantity is omitted, the 
| |entire field must be set to zero. 

j .. 

1 

8 

. 

j DA24MNM (Contains a member name of a partitioned data 

|set. If the name has less than eight 
| (characters, pad it to the right with blanks. 

|If the name is omitted, the entire field must 
| j contain blanks. 

I.._. _. i __ _ . 

1 

8 

. 

r - - T . . . . 1 

| DA24PSWD (Contains the password for the data set. If 

| |the password has less than eight characters, 

j j pad it to the right with blanks. If the 

| (password is omitted, the entire field must 

| (contain blanks. 

1 

1 

r t - -j 

| DA24DSP1 (Flag byte. Set the following bits to 

| (indicate the status of the data sets 

| 0000 .... (Reserved. Set these bits to zero. 

| .... 1... |SHR 

| .1. . j NEW 

| _ . .1. | MOD 

| . ..1 j OLD 

i. . .. - . 1.. .. _ 

r 1 

1 

. 

1 

1 

L J 

i 1 

| DA24DPS2 |Flag byte. Set the following bits to 

| |indicate the normal disposition of the data 

j |set: 

| 0000 .... |Reserved bits. Set them to zero. 

| 1... | KEEP 

| 1.. |DELETE 

| 1. |CATLG 

| 1 ,\ UNCATLG 


Figure 27. DAIR Parameter Block — Entry Code X f 24 f (Part 2 of 3) 
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Number of 
Bytes 


Field 


Contents or Meaning 


DA24 DPS3 


0000 .... 

.... 1 *.. 
. 1 .. 

.... ...1 


Flag byte. Set the following bits to 
indicate the abnormal disposition of the data 
set: 

Reserved bits. Set them to zero. 

KEEP 
DELETE 
CAT LG 
UNCATLG 


Flag byte. These flags indicate to the DAIR 
service routine what operation are to be 
performed: 

Indicate the type of units desired for the 
space parameters, as follows: 

Units are in average block length. 

Units are in tracks (TRKS)• 

Units are in cylinders (CYLS). 

Prefix userid to DSNAME. 

RLSE is desired. 

The data set is to be permanently allocated; 
it is not to be freed until specifically 
requested. 

A DUMMY data set is desired 
Attribute list name supplied. 

Reserved bit; set to zero. 


Reserved bytes; set them to zero. 


DA24 DSO 


1 .. • .... 

. 1 .. .... 

.. 1 . .... 

...0 00 .. 

.... .. 1 . 
.... ... 1 


A flag field. These flags are set by the 
DAIR service routine; they describe the 
organization of the data set to the calling 
routine. 

Indexed Sequential (IS). 

Physical Sequential (PS). 

Direct Organization (DO). 

Reserved bits. Set to zero. 

Partitioned Organization (PO) . 

Unmoveable. 


j 8 | DA24ALN [Attribute list name. 

i i i 


Figure 27. DAIR Parameter Block — Entry Code X*24 f (Part 3 of 3) 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 8, 12, 16, 20 


See the topic "Return Codes from DAIR" for return code meanings. 
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Code X^S* - Perform a List of PAIR Operations 


Build the DAIR Parameter Block shown in Figure 28 to request that DAIR 
perform a list of operations. This DAIR Parameter Block points to other 
DAPBs which request the operations to be performed. 


All valid DAIR functions are acceptable; however, code X , 14* or 
another code X f 28' are ignored. 

DAIR processes the requested operations in the order they are 
requested. 

DAIR processing stops with the first operation that fails. 


Number of 
Bytes 


Field 

DA28CD 


Contents or Meaning 


Entry code X , 0028' 


--- ^ 

Place in this field the number of operations | 
to be performed. 


DA28NOP 


--- 1 

DAIR fills this field with the address of the| 
DAIR Parameter Block for the first operation | 
that failed. If all operations are | 
successful, this field will contain zero upon| 
return from the DAIR service routine. If j 
this field contains an address, register | 
fifteen contains a return code. | 

----- i 

Place in this field the address of the DAIR | 
Parameter Block for the first operation you | 
want performed. Repeat this field, filling j 
it with the addresses of the DAPLs, for each j 
of the operations to be performed. j 


DA28PFOP 


DA280PTR 


Figure 28. DAIR Parameter Block — Entry Code X^S* 

After attempting the requested function, DAIR returns one of the 
following codes in register 15s 

Any code accepted by any of the other DAIR functions, except f 36' and 
f 40 f . 


For return code meanings see the topic "Return Codes from DAIR." 
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Code X* 2C" - Mark Data Sets as Not in Use 


Build the DAIR Parameter Block shown in Figure 29 to request that DAIR 
mark DSE entries associated with a Task Control Block as not in use. 
This allows TIOT entries to be reused. 


This is the code which the TMP should pass to DAIR prior to detaching 
a command processor. This code should also be issued by any command 
processor which attaches another command processor and detaches that 
command processor directly. 


Number of 
Bytes 


Field 


|Contents or Meaning 


2 

2 


DA2CCD 


|Entry code X , 002C* 


DA2CFLG 


|A flag field. Set the bits to indicate to 
|the DAIR service routine which data sets you 
|want marked not in use. 


I Hex setting 
|0000 
I 

| 0001 

I 

| 0002 

I 


Meaning 

Mark all data sets of the 
indicated TCB "not in use". 
Mark the specified DDNAME "not 
in use". 

Mark all DSEs associated with 
lower tasks "not in use". 


-- 

DA2CTCB |Place in this field the address of the TCB | 
|for the task whose data sets are to be marked 
|"not in use". 


1 


DA2CDDN |Place in this field the DDNAME to be marked 
|"not in use". DA2CFLG must be set to hex 
| 0001 . 

L_X_X_ 

Figure 29. DAIR Parameter Block — Entry Code X , 002C I 

After attempting the requested function, DAIR returns one of the 
following codes in register 15; 


0, 4 


For return code meanings see the topic "Return Codes from DAIR." 
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Code X*30 


Allocate a SYSOUT Data Set 


Build the DAIR Parameter Block shown in Figure 30 to request that DAIR 
allocate a SYSOUT data set. The exact action taken by DAIR is dependent 
upon the presence of the optional fields and the setting of bits in the 
control byte. To supply DCB information, provide the name of an 
attribute list that has been defined previously by a X , 34 i entry into 
DAIR. 


r - T 

Number of 
Bytes 

2 


1— 


Field 

DA30CD 


Contents or Meaning 
Entry code X f 0030'. 


-H 


DA30FLG 


Byte 1 


.000 0000 


Byte 2 


A flag field set by DAIR before returning to 
the calling routine. The flags have the 
following meaning: 


The data set is allocated but a seuunudiy 


error occurred, 
error code. 
Reserved bits. 


Register 15 contains an 


Set to zero. 


DA30DARC 


Reserved. Set to zero. 
+— 


This field contains the error code, if any, 
returned from the Dynamic Allocation 
routines. (See "Return Codes from Dynamic 
Allocation.") 


-H 


Reserved. Set this field to zero. 

-^ 

Place in this field the address of the DSNAME 
buffer. The DSNAME buffer is a 46 byte field 
with the following format: 

The first two bytes contain the length, in 
bytes, of the DSNAME; 

The next 44 bytes contain the DSNAME, left 
justified and padded to the right with 
blanks. 


DA3OPDSN 


DA30DDN 


This field contains the DDNAME for the data 
set. If a specific DDNAME is not required, 
fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the 
data is allocated. 




-f 


DA30UNIT 


- f 


Unit name desired. If blank, defaults to 
PSCBGPNM contents. If name is less than 
eight bytes, pad it at right with blanks. 


DA30SER 


Serial number desired. Only the first six 
bytes are significant. If the serial number 
is less than six bytes, it must be padded to 
the right with blanks. If the serial number 
is omitted, the entire field must contain 
blanks. 


H 


Figure 30. 


DA30BLK |Block size requested. This figure represents 
the average record length desired. 

,x_ ± _ 

DAIR Parameter Block — Entry Code X*30 f (Part 1 of 2) 
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Number of 
Bytes 


Field 


Contents or Meaning 


DA30PQTY 


Primary space quantity desired. The high 
order byte must be set to zero; the low order 
three bytes should contain the space quantity 
required. If the quantity is omitted, the 
entire field field must be set to zero. 


DA30SQTY 


Secondary space quantity desired. The high 
order byte must be set to zero; the low order 
three bytes should contain the secondary space 
quantity required. If the quantity is 
omitted, the entire field must be set to zero. 


DA30PGNM 


Place in this field the member name of a 
special user program to handle SYSOUT 
operations. Fill this field with blanks if 
you do not provide a program name. 


DA30FORM 


Form number. This form number indicates that 
the output should be printed or punched on a 
specific output form. It is a four character 
number. This field must be filled with blanks 
if this parameter is omitted. 


DA30OCLS 


SYSOUT class. Place a single alphameric 
character in either byte of this field and a 
blank in the other byte. The data set will be 
allocated to the message class, regardless of 
the class that you specify here. To place a 
SYSOUT data set in a class other than the 
message class, use DAIR entry code X*30', 
specifying any valid class. When the output 
has been written, specify the desired SYSOUT 
class either by using DAIR entry code or 

by issuing the FREE command. 


Reserved. Set this field to zero. 


DA30CTL 


.... . 1 .. 
.... .. 1 . 
.... . . . 0 

DA30ALN 


Flag byte. These flags indicate to the DAIR 
service routine what operations are to be 
performed. 

Indicate the type of units desired for the 
space parameters, as follows: 

Units are in average block length. 

Units are in tracks (TRKS) . 

Units are in cylinders (CYLS). 

Prefix userid to DSNAME 
RLSE is desired. 

The data set is to be permanently allocated; 
it is not to be freed until specifically 
requested. 

A DUMMY data set is desired. 

Attribute list name specified. 

Reserved bit; set to zero. 

Attribute list name. 


Figure 30. DAIR Parameter Block — Entry Code X'lO 1 (Part 2 of 2) 

After attempting the requested function, DAIR returns one of the 
following codes in register 15: 

0, 4, 12, 16, 20, 28 

See the topic "Return Codes from DAIR" for return code meanings. 
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Code X"34 


Build or Delete an Attribute Control Block (ATRCB) 


Build the DAIR Parameter Block shown in Figure 30.1 to request that DAIR 
construct an ATRCB f delete an ATRCB, or search the chain of ATRCBs for a 
specific name. The exact action taken by DAIR is dependent upon the 
setting of bits in the control byte. 

Note : When you request that DAIR construct an ATRCB, you must also 

build a DAIR Attribute Control Block (DAIRACB)• 


Number of 
Bytes 


Field 


Contents or Meaning 


-H 


2 

2 


DA34CD 


Entry code X , 0034 l . 


DA34FLG 


Byte 1 
DA34FIND 

1 ... ..... 
0 ... .... 

.000 0000 
Byte 2 


A flag field set by DAIR before returning to 
the calling routine. The flags have the 
following meaning: 


I 


An attribute list name was found. 

An attribute list name was not found. 
Reserved bits. Set to zero. 

Reserved. 


DA34DARC 


This field contains the code returned from 
the Dynamic Allocation routines. (See 
"Return Codes from Dynamic Allocation,.") 


i 


D A3 4 CTRL 

DA34SRCH 

1 ... .... 

DA34CHN 
.1.. .... 
DA34UNCH 
.. 1 . .... 
...0 0000 


Flag byte. These flags indicate to DAIR what 
operations are to be performed. 

Search the ATRCB chain for the attribute list 
name specified in field DA34NAME. 

Build and chain an attribute list (ATRCB). 

Delete an ATRCB from the chain. 

Reserved bits. Set to zero. 

Reserved. 


DA34NAME 


This field contains the name for the list of 
attributes. 




DA34ADDR 


This field contains the address of the DAIR 
Attribute Control Block (DAIRACB). 


-H 


Figure 31. DAIR Parameter Block — Entry Code X i 34* 
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DAIRACB - PAIR Attribute Control Block 


Build the DAIRACB shown in Figure 32 when you request that DAIR 
construct an attribute control block (ATRCB). Place the address of the 
DAIRACB into the DA34ADDR field of the code X'34' DAIR parameter block 
shown in Figure 31. 


r“ — t i 

Number of | 

Bytes | Field 

— i 

r ~ i 

1 

Contents or Meaning | 

r T 

8 1 
t 

Reserved. j 

8 | DAIMASK 

| DAILABEL 

1 

| DAIIN0UT 

| 1 . 

| DAIOUTIN 

I .1.. 

1 •.XX xxxx 

_ r j 

First 6 bytes and eighth byte are reserved. j 
Seventh-byte flags. These flags indicate thej 

INOUT/OUTIN options of the OPEN macro. | 

i 

Use the INOUT option. | 

Use the OUTIN option. | 

Reserved bits. | 

L _ . _ _ . . I 

1 

3 1 

L 

r — 7 

Reserved. | 

- t 

3 | DAIEXPDT 

1 

| DAIYEAR 
| DAIDAY 

1 

- ± 

r 1 

This field contains a data set expiration | 
date. | 
The first byte contains the expiration year, j 
The next 2 bytes contain the expiration day f | 
left justified (x'dddn). | 

.. - -j • • - - - 

2 | 

_ j. 

Reserved. | 

1 | DAIBUFNO 

1 

i 

This field contains the number of buffers | 

required. | 

T 

1 | DAIBFTEK 

1 

| .1. 

| .11. 

| ..1 . 

I ...1 .... 

| .... ..1. 

| .... ...1 

1 X... XX.• 

-j- 

| 

This field contains the buffer type and j 

alignment. | 

Simple buffering (S). | 

Automatic record area construction (A). | 

Record buffering (R) . | 

Exchange buffering (E). j 

Doubleword boundary (D). | 

Fullword boundary (F). | 

Reserved bits. j 

L __ _ 1 

2 1 DAIBUFL 

! | 

1 1 
This field contains the buffer length. | 

L _ .... .. - 1 

T 1 

1 | DAIEROPT 

| 1 . 

| .1 .. 

| ..1 . 

1 ... X XXXX 

r ' 7 

This field indicates the error options: | 
Accept error record. | 
Skip error record. j 
Abnormal ECT. | 
Reserved bits. j 

I_ . _ 

1 I DAIKEYLE 

4- 1 

r - 1 

This field contains the key length. | 

I 1 

6 1 

L X J 

Reserved. j 

L J 


Figure 32. DAIR Attribute Control Block (DAIRACB) (Part 1 of 2) 
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Number of 
Bytes 


Field 


Contents or Meaning 


DAIRECFM 

1 • • • «« « . 
• 1 •• • . « . 

11 . 

• • 1• • • • • 
. • . 1 . a . « 

.... 1 . . • 
• • • • • 1 • • 
• ■ • • . . 1 . 


This field indicates the record format: 
Fixed (F). 

Variable (V). 

Undefined (U). 

Track overflow (T). 

Blocked (B)• 

Standard Blocks (S). 

ASA printer characters (A). 

Machine control characters (M). 
Reserved bits. 


DAIOPTCD 

.. 1 . .... 
.... 1 ... 

. 1 . 

.X.X .X. X 


This field contains the error option codes: 
Write validity check (W). 

Chained scheduling (C). 

ANSI translate (Q). 

User totaling (T). 

Reserved bits. 


DAIBLKSI 


This field contains the maximum block size. 


DAILRECL 


This field contains the logical record 
length. 


DAINCP 


This field contains the maximum number of 
channel programs. 


|Reserved. 

_JL- 


Figure 32. DAIR Attribute Control Block (DAIRACB) (Part 2 of 2) 


The fields that you do not use must be initialized to zero. 
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Return Codes from DAIR 


DAIR returns a code in general register 15 to the calling routine. In 
addition f DAIR sets certain return codes in the DAxxDARC field of a DAIR 
Parameter Block. (See items preceded by an asterisk in "Return Codes 
from Dynamic Allocation.") 

The DAIR return codes have the following meanings 


CODE 

decimal 

0 

4 

8 


12 


16 

20 

24 

28 

32 


36 

40 


44 


48 


MEANING 


DAIR completed successfully. 

The parameter list passed to DAIR was invalid. 

An error occurred in a catalog management routine; the 
catalog management error code is stored in the CTRC field of 
the DAIR Parameter Block. 

An error occurred in dynamic allocation; the dynamic 
allocation error code is stored in the DARC field of the 
DAIR Parameter Block. 

No TIOT entries were available for use. 

The DDNAME requested is unavailable. 

The DSNAME requested is a member of a concatenated group. 

The DDNAME or DSNAME specified is not currently allocated f 
or the attribute list name specified was not found. 

The requested data set was previously permanently allocated, 
or was allocated with a disposition of new, and was not 
deleted. DISP=NEW cannot now be specified. 

An error occurred in a catalog information routine. 

The return area you provided for qualifiers was exhausted 
and more index blocks exist. If you require more 
qualifiers, provide a larger return area. 

The previous allocation specified a disposition of DELETE 
for this non-permanently allocated data set. Request 
specified OLD, MOD, or SHR with no volume serial number. 

Returned from DAIR STAE routine when an ABEND has occurred. 
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Return Codes from Dynamic Allocation 


Both DAIR and the Dynamic Allocation routines called by DAIR may return 
a code in the DAxxDARC field of the DAIR Parameter Block. 

Note : Codes that can be returned by DAIR are preceded by an asterisk. 

The asterisk is not part of the return code.) 

The return codes have the following meaning: 


RETURN CODE MEANING 
hexadecimal 


0000 

0004 

0008 

002w 


Dynamic Allocation completed successfully. 

Dynamic Allocation could not delete a table that was 
loaded using a LOAD macro instruction. The data set is 
still allocated. 

The temporary data set was freed and deleted. The 
disposition specified by the calling routine is invalid 
for a temporary data set. 

The data set was successfully freed, but the disposition 
(catalog or uncatalog) was unsuccessful. The hexadecimal 
digit 'w' is a code indicating the reason for the 
failure. 


w Explanation 

1 A control volume was required and a utility program must 
be used to catalog the data set. 


003x 


2 The data set to be cataloged had previously been 
cataloged or the data set to be uncataloged could not be 
located, or no change was made to the volume serial list 
of a data set with a disposition of CATLG. 

3 A specified index did not exist. 

4 The data set could not be cataloged because space was not 
available on the specified volume. 

5 Too many volumes were specified for the data set; because 
of this, not enough main storage was available to perform 
the specified cataloging. 

6 The data set to be cataloged in a generation index is 
improperly named. 

7 The data set to be cataloged was not opened and no 
density information was provided. (For dual density tape 
requests only). 

9 An uncorrectable input/output error occurred in reading 
or writing the catalog 

The data set was successfully freed, but the requested 
disposition (delete) was unsuccessful. The hexadecimal 
digit # x' is a code indicating the reason for failure. 
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0104 

0108 

010C 

0204 

0208 

020C 

0210 

0214 


*0218 

021C 


x Explanation 


1 The expiration date had not occurred. 

4 No device was available for mounting during deletion. 

5 Too many volumes were specified for deletion. 

6 Either no volumes were mounted or the mounted volumes 
could not be demounted to permit the remaining volumes to 
be mounted. 

8 The SCRATCH routine could not delete the data set from 
the volume. 

9 A job was cancelled and was deleted from any one of the 
following queues: 

Input Queues 
Background Reader Queue 
Hold Queue 

Automatic SYSIN Batching (ASB) Queue 
Output Queues 

Dynamic Allocation encountered an I/O error while 
attempting to read from SYSl.SYSJOBQE. 

Dynamic Allocation encountered an I/O error while 
attempting to write to SYSl.SYSJOBQE. 

Dynamic Allocation encountered an I/O error while 
enqueueing on SYSl.SYSJOBQE. 

Reserved. 

No space is available on SYSl.SYSJOBQE. 

The calling routine made a request for the exclusive use 
of a shared data set. The request can not be honored. 

The data set requested is not available. This data set 
is allocated to another job and its usage attributes 
conflict with this request. 

A direct access device is not available. To be available 
it must satisfy the following requirements: 

• It must be online. 

• It must be ready. 

• It must not be pending offline. 

• It must not be pending an unload. 

• It must be shareable. 

• A MOUNT message must not be currently outstanding. 

• The volume attributes must have been defined. 

The required volume was not mounted on an available 
device. Either DAIR or Dynamic Allocation can set this 
return code. 

(See Dynamic Allocation return code 214 for the 
requirements for an available device.) 

Incorrect unitname supplied. 
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0220 

through 

0264 Reserved. 

0268 Concatentaion was requested, but the DCBTIOT offset 

cannot be found in this job's DEB/DCB chain. 

0304 The ddname was not specified by the calling routine. 

0308 The ddname specified by the calling routine was not 

found. 

030C An invalid function code was specified by the calling 

routine. 

0310 The "exchange" option was specified by the calling 

program and the TIOT entry for the second (new) ddname 
could not be found. 

Restoring ddnames, as per this request, would have 
resulted in duplicate uuuames — duplicate ddnames are 
not permitted. 

Invalid characters are present in the ddname provided by 
the caller. 

031C Invalid characters are present in the membername provided 

by the caller. 

0320 Invalid characters are present in the dsname provided by 

the caller. 

0324 Invalid characters are present in the SYSOUT program name 

provided by the caller. 

0328 Invalid characters are present in the SYSOUT form number 

provided by the caller. 

032C An invalid SYSOUT class was specified by the caller. 

*0330 A membername was specified but the data set is not a 

partitioned data set. DAIR, not Dynamic Allocation, sets 
this return code. 

The supplied data set name exceeded 44 characters in 
length. 

The data set disposition specified by the caller is 
invalid. 

More than one mutually exclusive keyword (DSNAME, DUMMY, 
TERM, or SYSOUT) was specified. 

The dsname was not specified and the disposition was not 
"new". (If the disposition is "new" the dsname may be 
omitted.) 

0344 Dynamic Allocation was specified in a non-TSO 

environment. 

0348 

through 

034C Reserved. 


0334 

0338 

033C 

0340 


0314 


0318 
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0350 

0354 

0358 

0350 0360 
0364 

04 04 

0408 

04 OC 

0410 

0414 

0418 

*041C 

0420 

0424 

0428 

042C 

0430 

0504 


Jobname field contains zeros. This field may be blank, 
but may not contain zeros. 

Reserved. 

DELETE cannot be specified if the data set is shared. 
Reserved. 

JOBLIB DDNAME or STEPLIB DDNAME can not be specified. 
These data sets have been opened and thus cannot be 
allocated. 

The device to be freed is not a direct access device. 
(Only direct access devices are supported for dynamic 
allocation.) 

The new DDNAME is a duplicate of a DDNAME in the TIOT. 

The calling routine requested allocation of a file name 
(DDNAME) already used for the job. 

The specified ddname is associated with a DYNAM entry. 
DYNAM entries may not be concatenated. 

The specified ddname is allocated to a data set. The 
ddname must be associated with a DYNAM entry. 

The specified ddname is already allocated to a terminal 
entry (TERM=TS)• 

The referenced data set is a member of a concatenated 
data group. If the data set was dynamically concatenated 
it must be deconcatenated before this request can be 
honored. If concatenated at LOGON, the data set may not 
be freed until LOGOFF. 

The referenced data set is a multi-volume data set. 

Multi-volume data sets (data sets on more than one 
volume) are not supported by Dynamic Allocation. Either 
DAIR or Dynamic Allocation can set this return code. 

The specified ddname is associated with an open data set. 
(A data set must be closed to be used by Dynamic 
Allocation.) 

Reserved. 

The specified ddname is part of a previously allocated 
space. Dynamic Allocation cannot free it. 

The ddname to be freed is associated with a generation 
data group. Generation data groups are not supported in 
Dynamic Allocation. 

The specified ddname is associated with a passed data 
set. Passed data sets cannot be freed or converted. 

A serious error of undetermined cause has occurred 
involving system data. 
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*x7zz 


A Dynamic Allocation return code of this form is 
constructed of an identifier (x) representing the system 
macro instruction returning the code, and the code itself 
(zz) returned by the macro instruction. 

If "x" equals 1, the LOCATE macro instruction 
returned the code. DAIR, not Dynamic Allocation, 
returns this code. 

If "x" equals 4, the DADSM macro instruction 
returned the code. 

If "x" equals 6, the OBTAIN macro instruction 
returned the code. DAIR, not Dynamic Allocation, 
returns this code. 

"zz" is the low order byte from register 15 as returned 
by the macro instruction. 

The return codes for the LOCATE and the OBTAIN macro 
instructions are described in Data Management for Gystem 
Programmers . 

The return codes for the DADSM macro instruction are as 
follows: 

Code Meaning 

00 The operation completed successfully. 

04 Duplicate name DSCB. 

08 No available DSCB's in the VTOC. 

0C A permanent I/O error occurred in reading or 
writing a DSCB. 

10 The absolute track requested is not available. 

14 The quantity of space requested is not available. 

18 The record length specified is greater than the 
track length. 

30 The number of tracks requested for a split 

cylinder data set is greater than the number of 
tracks per cylinder. 

34 The disk pack is a DOS volume and the request is 
not absolute track. 

38 The volume does not have enough space for the 
directory. 

80 The directory space requested is larger than the 
primary space requested. 
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Using BSAM or QSAM for Terminal I/O 


The Basic Sequential and Queued Sequential access methods provide 
terminal I/O support for programs operating under the Time Sharing 
Option. For a complete discussion of the use of BSAM and QSAM, see the 
publication Data Management Services . 


The major benefit of using BSAM or QSAM to process terminal I/O under 
TSO is that programs using these access methods do not become TSO 
dependent or device dependent and may execute either under TSO or in the 
batch environment. Therefore, your existing programs that use BSAM or 
QSAM for I/O may be used under TSO without modification or 
recompilation. 

This section describes: 


• The BSAM/QSAM macro instructions 

• SAM Terminal routines 

• Record formats, buffering techniques, and processing modes 

• Specifying the terminal line size 

• End of file (EOF) for input processing 

• Modifying DD statements for batch or TSO processing 
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BSAM/QSAM Macro Instructions 


Some of the BSAM and QSAM access method routines have been modified to 
provide special services under TSO; others provide the same function 
that is provided in a batch environment. Those BSAM/QSAM macro 
instructions that are not relevent to terminal I/O act as no-ops. All 
of the BSAM/QSAM macro instructions, when executed in the batch 
environment, provide the non-terminal functions as explained in Data 
| Management Macro Instructions . Figure 33 shows the functions performed 
by the BSAM and QSAM macro instructions when used for terminal I/O. 
Following the table are more detailed explanations of the GET, PUT, 
PUTX, READ, WRITE, and CHECK macro instructions. 


T-T- 

|Terminal 

QSAM|Interpretation 


SAM Macro 
Instruction 


BSP 


BSAM 


I NOP 


BUILD 


JAs in batch processing, the BUILD macro 
|instruction causes a buffer pool to be 
|constructed in a user-provided main storage 
|area. 


BUILDRCD 


CHECK 


h~ 


| NOP 

-+ - 

| Takes an EODAD exit after a READ EOF 

I after a WRITE. 


-4 

NOP 


CLOSE 


|The CLOSE macro instruction frees the control 
(blocks built to handle I/O and deletes the 
|loaded SAM terminal routines. 


CNTRL 


h~ 


NOP 


FEOV 


I NOP 


FREEBUF 


X 


|As in batch processing, the FREEBUF macro 
(instruction causes the control program to 
| return a buffer to the buffer pool assigned to 
|the specified data control block. 


FREEPOOL 


X |As in batch processing, the FREEPOOL macro 
(instruction causes an area of main storage, 

|previously assigned as a buffer pool for a 
(specified data control block, to be released. 


GET 


|The GET macro instruction obtains data from 
|the terminal via the TGET macro instruction. 


GETBUF 


(As in batch processing, the GETBUF macro 
(instruction causes the control program to 
|obtain a buffer from the buffer pool assigned 
(to the specified data control block, and to 
|return the address of the buffer in a 
(designated register. 


GETPOOL | X | X |As in batch processing, the GETPOOL macro 

(instruction causes a buffer pool to be 
(constructed in a main storage area provided by 
| the cont rol pro gr am. 

L_X-X-X- 

Figure 33. BSAM/QSAM Function under TSO (Part 1 of 2) 
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r i 

| SAM Macro 
| Instruction 

I 

BSAM|QSAM 
.j. 

r - i 

Terminal | 

Interpretation | 

_ . ... | 

| NOTE 

j. . 

x | 

NOP | 

L . J 

] OPEN 

L _ ...._. ... 1 

X I X 

1 

1 

+ -1 

r 1 

The OPEN macro instruction loads the proper | 

SAM terminal I/O routines and constructs the j 
necessary control blocks. j 

i 

r 

| POINT 

L ... 

t 

X I 

h "f 

1 7 

NOP | 

|_ _ „ .| 

1 

| PRTOV 

L _ _ _ 

X I X 

NOP | 

r 

| PUT 

L 

■f 

1 X 

1 

_J_ 

r 1 

The PUT macro instruction routes data to the | 
terminal via the TPUT macro instruction. | 

r 1 

| PUTX 

-T- 

1 X 

1 

The PUTX macro instruction routes data to the j 
terminal via the TPUT macro instruction. | 

L . - _ _.-...I 

r 1 

| READ 

L 

r t 1 

x | 
i 

_L_ 

r — — — - - T 

The READ macro instruction obtains data from | 
the terminal via the TGET macro instruction. j 

—. _ i 

r 1 

| RELSE 
l 

-r- 

1 x 

__j_ 

r ■ -- — " — T 

NOP | 

r 

| SETPRT 

X 1 X 

r 1 

NOP j 

_ -j 

r 1 

| TRUNC 

L _ 

__ 

1 X 

NOP | 

L _ _ ___ _ . i 

r 

| WRITE 

L J 

x 1 

1 

L X J 

The WRITE macro instruction routes data to the| 
terminal via the TPUT macro instruction. | 

L J 


Figure 33. BSAM/QSAM Function under TSO (Part 2 of 2) 


SAM TERMINAL ROUTINES 

The GET, PUT, PUTX, READ, WRITE, and CHECK macro instructions perform 
differently in terminal I/O than the way they do in the batch 
environment. Descriptions of these differences are presented here, but 
for a detailed explanation of how to use the macro instructions, see 
Data Management Macro Instructions . 

GET 

The GET macro instruction causes a record to be retrieved from the 
terminal and placed in either the first buffer of the buffer pool 
control block (locate mode) or in a user specified area (substitute or 
move mode). In either case, the address of the record is returned in 
register 1. 

The record is moved via a TGET macro instruction which does not 
return control until the transfer of data is completed. 

The input to the GET macro instruction consists of the DCB address 
and the user's area address (omitted for locate mode). The output is 
edited (i.e., specially-indicated characters are deleted from the 
message). 

When the terminal user types /*, end of * file is indicated and control 
is passed to the problem program's EODAD routine. If no EODAD routine 
is specified, the job will ABEND with a system code of 337. 
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PUT and PUTX 


Both the PUT and the PUTX macro instructions cause a record to be 
written to a terminal. This transfer of data is accomplished with the 
TPUT macro instruction which does not return control until the transfer 
is completed. 

In locate mode, the first use of PUT or PUTX causes an address 
pointing to a buffer to be returned in register 1. The first record is 
placed in this buffer by the problem program and is written out when the 
next PUT or PUTX for the same data control block (DCB) is issued. 
Succeeding records are written in the same manner. The last record is 
written at CLOSE time. 

In move or substitute mode, the PUT or PUTX macro instruction moves a 
record from the user-specified work area to the terminal. You must 
supply the work area address to the PUT macro instruction. 

The input to the PUT and PUTX macro instruction consists of the DCB 
address and the user's area address (omitted for locate mode). 

READ 


The READ macro instruction causes a block of data to be retrieved from 
the terminal and placed in a user-designated area in main storage. This 
transfer of data is done via a TGET macro instruction which does not 
return control before the transfer is completed. 

The input to the READ macro instruction consists of the string of 
parameters explained in Data Management Macro Instructions . 

WRITE 

The WRITE macro instruction causes a block of data to be written from 
the user-specified area to the terminal. This transfer of data is done 
via a TPUT macro instruction which does not return control before the 
transfer is completed. 

The input to the WRITE macro instruction consists of the string of 
parameters explained in Data Management Macro Instructions . 

CHECK 


The CHECK macro instruction used after a WRITE macro instruction results 
in a NOP. When it is used after a READ macro instruction, it performs 
as a NOP unless an end of file (EOF) condition is encountered. The end 
of file signal from the terminal is /*. When end of file is 
encountered, CHECK takes the EODAD exit specified in the data control 
block. If no EODAD exit is specified, CHECK will cause the job to ABEND 
with a system code of 337. 

The input to the CHECK macro instruction is the address of the 
problem program's data event control block (DECB). 
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Record Formats, Buffering Techniques, and Processing Modes 


All record formats — Fixed (F), Variable (V), and Undefined (U) — are 
supported under TSO. Before passing the data to the problem program, 

TSO automatically generates the first 4 bytes of control information for 
V format records coming in from the terminal. When you send V format 
records to the terminal, TSO automatically removes the control 
information before writing the line. 

Both simple and exchange buffering techniques are supported, as are 
all four processing modes for the queued access method. 


Specifying Terminal Line Size 

If the LRECL and BLKSIZE fields are not specified in the DCB, the 
terminal line size default (or the line size the terminal user has 
specified via the TERMINAL command) is merged into the data control 
block fields as if it came from the label of the data set. 

For BSAM, BLKSIZE is used by TSO to determine the length of the text 
line it is to process. For both BSAM and QSAM, if the text entered from 
the terminal is shorter than the value specified for LRECL, and if F 
format is used, blanks are supplied on the right. For either access 
technique, if the text entered is longer than BLKSIZE or LRECL, the next 
GET or READ retrieves the remainder of the message. If the record 
generated by the problem program is longer than the specified line size, 
multiple lines are printed at the terminal. 


End of File (EOF) for Input Processing 


The sequential access method GET and CHECK terminal routines recognize 
/* from the terminal as an end of file (EOF). The EODAD exit in the 
data control block is taken for the EOF condition. If no EODAD exit has 
been specified, and an EOF has been signaled from the terminal, the job 
ABENDS with a system code of 337. 


Modifying DD Statements for Batch or TSO Processing 


A new parameter, TERM=TS, has been provided for the JCL Data Definition 
(DD) statement. 

TERM=TS, when added to a DD statement defining an input or an output 
data set, is ignored in the batch processing environment, but under TSO 
indicates to the system that the unit to which I/O is being addressed is 
a time sharing terminal. Thus a user who wants his job to run in either 
the foreground or the background could provide a DD statement as 
follows: 

r- 1 

|//DD1 DD TERM=TS,SYSOUT=A | 

L-J 

In this example the output device is defined as a terminal under TSO 
processing, and as the SYSOUT device during batch processing. For a 
complete description of the TERM=TS parameter, see Job Control Language 
Reference. 
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Using the TSO I/O Service Routines for Terminal I/O 


The TSO I/O Service Routines process terminal I/O requests initiated by 
the Terminal Monitor Program (TMP), Command Processors (CPs), and other 
service routines. If you write your own Command Processors, or replace 
the TSO-supplied Terminal Monitor Program with one of you own design, 
you should use the I/O Service Routines to process terminal I/O. 

The I/O Service Routines -- STACK, GETLINE, PUTLINE, and PUTGET — 
offer the following features: 

1. They provide an interface between an I/O request and the TGET and 
TPUT supervisor calls. 

2. They provide a method of selecting sources of input other than the 
terminal. Requests for input can be directed to an in-storage list 
as well as to the terminal. 

3. They provide a message formatting facility with which you can 
insert text segments into a basic message format, and print or 
inhibit the printing of message identifiers at the terminal. 

4. They process requests for more information (question mark 
processing), and they analyze processing conditions to determine if 
I/O requests should be disregarded or honored. 

The I/O Service Routines build, modify, or make use of various 
control blocks. The following control block DSECTS are provided in 
SYSl•MACLIB for your uses 

IKJCPPL - The Command Processor Parameter List 
IKJIOPL - The Input Output Parameter List 
IKJSTPB - The STACK Parameter Block 
IKJGTPB - The GETLINE Parameter Block 
IKJPTPB - The PUTLINE Parameter Block 
IKJPGPB - The PUTGET Parameter Block 
IKJLSD - The List Source Descriptor 
IKJECT - The Environment Control Table 

You pass control to the I/O service Routines and indicate the 
functions you want performed by coding the operands you require in the 
List and the Execute forms of the I/O Service Routine macro 
instructions. Each of the I/O Service Routine macro instructions 
(STACK, GETLINE, PUTLINE, and PUTGET) has a List and an Execute form. 

The List form of each Service Routine macro instruction initializes 
the parameter blocks according to the operands you code into the macro 
instruction. 

The Execute form is used to modify the parameter blocks and to 
provide linkage to the Service Routines, and can be used to set up the 
Input Output Parameter List. The Input Output Parameter List contains 
addresses required by the I/O services routines. 
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This following paragraphs describe: 

• The Interface with the I/O Service Routines 

• Passing Control to the I/O Service Routines 

• The I/O Service Routines Macro Instructions 

STACK 

GETLINE 

PUTLINE 

PUTGET 


Interface with the I/O Service Routines 


When the Terminal Monitor Program attaches a Command Processor, register 
1 contains a pointer to a Command Processor Parameter List (CPPL) 
containing addresses required by the Command Processor. The CPPL is 
located in subpool 1, which is read-only storage for the Command 
Processors. The control block interface between the TMP and an attached 
CP is shown in Figure 34. 



Figure 34. Control Block Interface Between TMP and CP 
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THE COMMAND PROCESSOR PARAMETER LIST 


You must pass certain addresses contained in the CPPL to the I/O Service 
Routines. Your user-written Command Processors can access the CPPL via 
the symbolic field names contained in the IKJCPPL DSECT by using the 
address received in register 1 as a starting address for the DSECT. The 
use of the DSECT is recommended since it protects the Command Processor 
from any changes to the CPPL. 

The Command Processor Parameter List, as defined by the IKJCPPL 
| DSECT, is a four word parameter list. Figure 35 describes the contents 
of the CPPL. (See Figure 5, the Test Parameter List, for a definition 
of each table whose address is in the CPPL.) 


r t 

| Number of | 

| Bytes | Field Name 

j | _ 

r- ” -- “ - 1 

1 

Contents or Meaning | 

L _ J 

| 4 | CPPLCBUF 

r I 

The address of the command buffer. | 

4 

j 4 | CPPLUPT 

1 1 

The address of the User's Profile Table j 

(UPT). | 

.. .. . j 

1 T 1 

| 4 | CPPLPSCB 

1 1 

i 

The address of the Protected Step Control | 

Block (PSCB)• j 

1 

| | | 

i 4 i CPPLECT 

1 1 1 

L X J 

T 

The address of the Environment Control Table | 
(ECT). | 


Figure 35. The Command Processor Parameter List (CPPL) 

You must place the addresses of the User Profile Table and the 
Environment Control Table in another control block, the Input Output 
Parameter List, and pass them to the I/O Service Routines. 


THE INPUT OUTPUT PARAMETER LIST 

The I/O Service Routines use two of the pointers contained in the 
Command Processor Parameter List — the pointer to the User Profile 
Table and the pointer to the Environment Control Table. These addresses 
are passed to the Service Routines in another parameter list, the Input 
Output Parameter List (IOPL). Before executing any of the TSO I/O macro 
instructions (GETLINE, PUTLINE, PUTGET, or STACK) you must provide an 
IOPL and pass its address to the I/O Service Routine. There are two 
ways you can construct an IOPL: 

1. You can build and initialize the IOPL within your code and place a 
pointer to it in the execute form of the I/O macro instruction. 

2. You can provide space for an IOPL (4 fullwords), pass a pointer to 
it together with the addresses required to fill it, to the execute 
form of the I/O macro instruction, and let the I/O macro 
instruction build the IOPL for you. 

The Input Output Parameter List, as defined by the IKJIOPL DSECT, is 
| a four word parameter list. Figure 36 describes the contents of the 
IOPL. 
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Number of 
Bytes 


Field Name 


Contents or Meaning 


IOPLUPT 


The address of the User Profile Table from 
the CPPLUPT field of the Command Processor 
Parameter List. 


IOPLECT 


The address of the Environment Control Table 
from the CPPLECT field of the CPPL. 


IOPLECB 


The address of the command processor's Event 
Control Block (ECB)• The ECB is one word of 
storage f declared and initialized to zero by 
the command processor. Command processors 
with attention exits can post this ECB after 
an attention interruption to cause active 
service routines to exit. 


IOPLIOPB 


The address of the parameter block created by 
the list form of the I/O macro instruction. 
There are four types of parameter blocks, one 
for each of the I/O Service Routines: 

Stack Parameter Block (STPB) 

Getline Parameter Block (GTPB) 

Putline Parameter Block (PTPB) 

Putget Parameter Block (PGPB) 


Figure 36. The Input Output Parameter List 


The Parameter Block pointed to by the fourth word (IOPLIOPB) of the 
I/O Parameter List is built and modified by the I/O Service routine 
macros themselves. It is created and initialized by the list form of 
the I/O macro instruction, and modified by the execute form. Thus you 
can use the same parameter block to perform different functions. All 
you need to do is code different parameters in the execute forms of the 
macro instructions; these parameters provide those options not specified 
in the list form, and override those which were specified. Each of 
these parameter blocks — the STACK, GETLINE, PUTLINE, and PUTGET 
Parameter blocks — is described in the separate sections on each of the 
I/O macro instructions. 


Figure 37, an extension of Figure 34, summarizes the control block 
interfaces established between the Terminal Monitor Program and an I/O 
Service Routine. 
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Figure 37. Control Block Interface Between TMP and I/O Service Routine 
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Passing Control to the I/O Service Routines 


There are two ways you can pass control to the I/O Service routines. 

1. You can issue a LOAD macro instruction for the load module 
containing the required service routine, and code the entry point 
address of that routine in the TSO I/O macro instruction via the 
ENTRY parameter. In this case, the I/O macro instruction will 
execute a branch and link register instruction (BALR) using the 
entry point as the branch address. All of the TSO Terminal I/O 
Service Routines are contained within the IKJPTGT load module. 
Their entry points are: 

Service Routine 

• STACK 

• GETLINE 

• PUTLINE 

• PUTGET 

If your region space requirements are critical, you can use the 
DELETE macro instruction to release the main storage area occupied 
by the load module when you have finished with your terminal I/O. 

2. You can issue the I/O macro instruction and not include the ENTRY 
parameter. In this case, the I/O macro instruction generates a 
LINK macro instruction to invoke the I/O Service Routine. 

The I/O Service Routine Macro Instructions 

The I/O Service routines — STACK, GETLINE, PUTLINE, and PUTGET — each 
perform a specific I/O function: 

• STACK determines the source of input. 

• GETLINE obtains a line of input. 

• PUTLINE puts a line of output to the terminal. 

• PUTGET puts a line to the terminal and gets a line in response. 

In order to perform these functions, the I/O macro instructions use 
the control blocks explained in the section •INTERFACE WITH THE I/O 
SERVICE ROUTINES", and other, more individualized control blocks, the 
parameter blocks. Each of the I/O macro instructions has a list and an 
execute form. The list form sets up the Parameter Block required by 
that I/O service routine; the execute form can be used to set up the 
Input Output Parameter List, and to modify the parameter block created 
by the list form of the macro instruction. 

The Parameter Block required by each of the I/O service routines is 
different, and each one may be referenced through a DSECT. The 
Parameter Blocks and the DSECTS used to reference them are: 

• The STACK Parameter Block IKJSTPB 

• The GETLINE Parameter Block IKJGTPB 

• The PUTLINE Parameter Block IKJPTPB 

• The PUTGET Parameter Block IKJPGPB 

Each of these blocks is explained in the section describing the I/O 
macro instruction that builds it. 
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Entry Point 

IKJSTCK 

IKJGETL 

IKJPUTL 

IKJPTGT 



STACK 


CHANGING THE SOURCE OF INPUT 


Use the STACK macro instruction to establish and to change the source of 
input- The currently active input source is described by the top 
element of the Input Stack, an internal pushdown list maintained by the 
I/O service routines. The first element of the Input Stack is 
initialized by the Terminal Monitor Program (TMP), and cannot thereafter 
be changed or deleted. The TSO-supplied TMP initializes this first 
element to indicate the terminal as the current input source. The STACK 
Service Routine adds an element to the input stack or deletes one or 
more elements from it, and thereby changes the source of input for the 
other I/O service routines. 

This topic describes: 

• The List and Execute forms of the STACK macro instruction. 

• The Sources of input. 

• The STACK Parameter Block. 

• The List Source Descriptor. 

• Return codes from STACK. 

Coding examples are included where needed. 


The STACK Macro Instruction - List Form 


The list form of the STACK macro instruction builds and initializes a 
STACK Parameter Block (STPB), according to the operands you specify in 
the macro. The STACK parameter Block indicates to the STACK service 
routine which functions you want performed. Figure 38 shows the list 
form of the STACK macro instruction; each of the operands is explained 
following the figure. Appendix B describes the notation used to define 
macro instructions. 


[symbol] 


- T -~ 


STACK 


TERM=* 


STORAGE=(element address 


DELETE= 




L_X_X- 

Figure 38. The List Form of the STACK Macro Instruction 


,MF=L 


TERM=* 

Add a terminal element to the input stack. 


STORAGE=element address 

Add an in-storage element to the input stack. The element address 
is the address of the List Source Descriptor (LSD). The LSD is a 
control block, pointed to by the Stack Parameter Block, which 
describes the in-storage list. The in-storage element must be 
further defined as a SOURCE, PROCN, or PROCL list. SOURCE is the 
default. 


SOURCE 

The element to be added to the Input Stack is an in-storage source 
data set. 
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PROCN 

The element to be added to the Input Stack is a command procedure 
and NOLIST option has been specified. 


PROCL 

The element to be added to the Input Stack is a command procedure 
and the LIST option has been specified. Each line read from the 
command procedure is written to the terminal. 

DELETE= 

Delete an element or elements from the Input Stack. The element to 
be deleted must be further defined as TOP, PROC f or ALL. 


TOP 

The topmost element (the element most recently added to the Input 
Stack) is to be deleted. 

PROC 

The current procedure element is to be deleted from the Input 
Stack. If the top element is not a PROC element, all elements down 
to and including the first PROC element encountered are to be 
deleted. 

ALL 

All elements are to be deleted from the Input Stack except the 
bottom element (the first element). 

MF=L 

Indicates that this is the List form of the macro instruction. 


NOTE : In the List form of the macro instruction, only the following is 

required: 

r--- A —i 

|STACK MF=L | 

L_J 

The other operands and their sublists are optional because they may be 
supplied by the execute form of the macro instruction: 



The operands you specify in the list form of the STACK macro 
instruction set up control information used by the STACK Service 
Routine. The TERM=*, STORAGE=, and DELETE= operands set bits in the 
STACK Parameter Block. These bit settings indicate to the STACK Service 
Routine which options you wish performed. 
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The STACK Macro Instruction - Execute Form 


Use the execute form of the STACK macro instruction to perform the 
following three functions: 

1. You can use it to set up the Input Output Parameter List (IOPL). 

2. You can use it to initilize those fields of the STACK Parameter 
Block not initialized by the list form of the macro instruction, or 
to modify those fields already initialized. 

3. You use it to pass control to the STACK Service Routine which 
modifies the Input Stack. 

Figure 39 shows the Execute form of the STACK macro instruction; each 

of the operands is explained following the figure. Appendix B describes 

the notation used to define macro instructions. 

r -- -t- t-*- 1 

| [symbol] j STACK |[PARM=parameter address][ f UPT=upt address] | 

j j j j 

| | | [,ECT=ect address][,ECB=ecb address] | 



j | | r, ENTRY= f entry address)"] ,MF=(E, (list address)) | 

I 111 <15) fl \ (1) f | 

L-J-J--- ± -.-J 

Figure 39. The Execute form of the STACK Macro Instruction 
PARM=parameter address 

Specifies the address of the 2-word STACK Parameter Block (STPB). 

It may be the address of the list form STACK macro instruction. 

The address is any address valid in an RX instruction, or the 
number of one of the general registers 2-12 enclosed in 
parentheses. This address will be placed in the Input Output 
Parameter List (IOPL). 

UPT=upt address 

Specifies the address of the User Profile Table (UPT). This 
address may be obtained from the Command Processor Parameter List 
pointed to by register one when the Command Processor is attached 
by the Terminal Monitor Program. The address may be any address 
valid in an RX instruction or the number of one of the general 
registers 2-12 enclosed in parentheses. This address will be 
placed in the Input Output Parameter List (IOPL). 

ECT=ect address 

Specifies the address of the Environment Control Table (ECT). This 
address may be obtained from the CPPL pointed to by register 1 when 
the Command Processor is attached by the Terminal Monitor Program. 
The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in 
parentheses. This address will be placed in the IOPL. 
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ECB=ecb address 

Specifies the address of an Event Control Block (ECB). This 
address will be placed into the IOPL. You must provide a one-word 
Event Control Block and pass its address to the STACK service 
routine by placing it into the IOPL* The address may be any 
address valid in an RX instruction or the number of one of the 
general registers 2-12 enclosed in parentheses. 


TERM=* 

Add a terminal element to the Input Stack. 


STORAGE=element address 

Add an in-storage element to the Input Stack. The element address 
is the address of the List Source Descriptor (LSD). The LSD is a 
control block, pointed to by the Stack Parameter Block, which 
describes the in-storage list. The in-storage list must be further 
defined as a SOURCE, PROCN, or PROCL list. SOURCE is the default. 


SOURCE 

The element to be added to the Input Stack is an in-storage source 
data set. 


PROCN 

The element to be added to the Input Stack is a command procedure 
and the NOLIST option has been specified. 

PROCL 

The element to be added to the Input Stack is a command procedure 
and the LIST option has been specified. Each line read from the 
command procedure is written to the terminal. 


DELETE 

Delete one or more elements from the input stack. Specify which 
element, either TOP, PROC, or ALL. 


TOP 

The topmost element (the element most recently added to the input 
stack) is to be deleted. 

PROC 

The current procedure element is to be deleted from the input 
stack. If the top element is not a procedure element, all elements 
down to and including the first procedure element encountered are 
to be deleted. 

ALL 

All elements are to be deleted from the input stack except the 
bottom element (the first element). 

ENTRY=entry address or (15) 

Specifies the entry point of the STACK service routine. The 
address may be any address valid in an RX instruction or (15) if 
the entry point address has been loaded into general register 15. 

If ENTRY is omitted, a LINK macro instruction will be generated to 
invoke the STACK Service Routine. 


MF=E 

Indicates that this is the Execute form of the macro instruction. 
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listaddr 

( 1 ) 

The address of the 4-word Input Output Parameter List (IOPL). This 
may be a completed IOPL that you have built, or it may be 4 words 
of declared storage that will be filled from the PARM, UPT, ECT, 
and ECB operands of this Execute form of the STACK macro 
instruction. The address is any address valid in an RX instruction 
or (1) if the parameter list address has been loaded into general 
register 1. 


NOTE : In the Execute form of the STACK macro instruction only the 

following operands are required: 

[sTACK MF=(E,(list address 1) 

I \ (1) / 

L_ 


1 


J 


The PARM=, UPT=, ECT~, and ECE- operands are not required if yuu hcive 
built an IOPL in your own code. 

The other operands and their sublists are optional because they may be 
supplied by the list form of the macro instruction: 


r - n 

j TERM=* 

I or 

( , SOURCE 
,PROCN 
,PROCL 



L_J 



The ENTRY= operand need not be coded in the macro instruction. If it 
is not, a LINK macro instruction will be generated to invoke the I/O 
Service routine. 

The operands you specify in the execute form of the STACK macro 
instruction are used to set up control information used by the STACK 
service routine. You can use the PARM=, UPT=, ECT=, and ECB= operands 
of the STACK macro instruction to complete, build, or alter an IOPL. 

The TERM=* # STORAGE=, and DELETE= operands set bits in the STACK 
Parameter Block. These bit settings indicate to the STACK Service 
Routine which options you want. 

Sources of Input 

The input sources provided are defined as follows: 

1. Terminal. 

If the terminal is specified in the STACK macro instruction as the 
input source, all input and output requests through GETLINE, 
PUTLINE, and PUTGET are read from the terminal and written to the 
terminal. The user at the terminal controls the Time Sharing 
Option by entering commands; the system processes these commands as 
they are entered; and returns to the user for another command. 
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2. In-Storage List 

An in-storage list can be either a list of commands or a source 
data set. It may contain variable length records (with a length 
header) or fixed length records (no header and all records the same 
length). In either case, no one record on an In-storage list may 
exceed 256 characters. 

The in-storage list can be specified as one of two types through 
the PROC or SOURCE parameters of the STACK macro instruction. 

• PROC - Indicates that the in-storage list is a command procedure 
— a list of commands to be executed in the order specified. If 
you specify PROC, requests through GETLINE are read from the 
in-storage list, but PROMPT requests from the executing command 
processor are suppressed. MODE messages, those messages normally 
sent to the terminal requesting entry of a command or a 
sub-command, are not sent but a command is obtained from the 
in-storage list. If the LIST option was specified in the STACK 
macro instruction when the command procedure was added to the 
input stack, the command is displayed at the terminal. 

• SOURCE - Indicates that the in-storage list is a source data set. 
Requests through GETLINE are read from the in-storage list, but 
PROMPT requests from the executing command processor are honored 
if prompting is allowed, and a line is requested from the 
terminal. MODE messages are handled the same way as with PROC, 

No LIST facility is provided with SOURCE records. 

Building the STACK Parameter Block 


When the list form of the STACK macro instruction expands, it builds a 
two word STACK Parameter Block (STPB). The list form of the macro 
instruction initializes this STPB according to the operands you have 
coded. This initialized block, which you may later modify with the 
execute form of the macro instruction, indicates to the I/O service 
routine the functions you want performed. 

By using the list form of the macro instruction to initialize the 
block, and the execute form to modify it, you can use the same STPB to 
perform different STACK functions. Keep in mind however, that if you 
specify an operand in the execute form of the macro instruction, and 
that operand has a sublist as a value, the default values of the sublist 
will be coded into the STPB for any of the sublist values not coded. If 
you do not want the default values you must code each of the values you 
require, each time you change any one of them. 

As an example: If you code the list form of the STACK macro 
instruction as follows: 


r- 1 

| STACK STORAGE=(element address,PROCN),MF=L | 

L-J 


and then override it with the execute form of the macro instruction as 
follows: 


|STACK STORAGE^(new element address),MF=(E,list address) j 

L-J 

The element code in the STACK Parameter Block would default to SOURCE, 
the default value. If the new in-storage list was another PROCN list, 
you would have to respecify PROCN in the execute form of the macro 
instruction. 
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The STACK Parameter Block is defined by the IKJSTPB DSECT. Figure 4 0 
describes the contents of the STPB. 


Number of 
Bytes 


- + -+ 


i— 


Field 
none 


...1 _ 


xxxx 


Contents or Meaning 

- * 

Operation code: A flag byte which describes 
the operation to be performed. 

One element is to be added to the top of the 
Input Stack. 

The top element is to be deleted from the 
Input Stack. 

The current procedure element is to be 
deleted from the Input Stack. If the top 
element is not a PROC element, all elements 
down to and including the first PROC element 
encountered are deleted,, except the bottom 
element. 

All elements except the bottom one (the first 
element) are to be uexeteu. 

Reserved bits. 


* 


none 

1 ... .... 

.1 . 

.... .. 0 . 

. 1 . 


•cXX XX.. 


Element code: A flag byte describing the 
element to be added to the Input Stack. 

A terminal element. 

An in-storage element. 

The in-storage element is a source element. 
The in-storage element is a procedure 
element. 

The list option (PROCL) has been specified. 
Reserved bits. 


-H 


2 

4 


Reserved 


STPBALSD 


The address of the List Source Descriptor 
(LSD). An LSD describes an in-storage list. 
If the input source is the terminal, or if 
DELETE has been specified, this field will 
contain zeros. 


Figure 40. The STACK Parameter Block 
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If the TERM or DELETE operands have been coded in the STACK macro 
instruction, the second word of the Stack Parameter Block will contain 
zeros and the control block structure will end with the STPB. Figure 41 
describes this condition. 



Figure 41. STACK Control Blocks: No In-Storage List 

To add an in-storage list element to the input stack, you must 
describe the in-storage list and pass a pointer to it to the STACK I/O 
service routine. You do this by building a List Source Descriptor 
(LSD) . 
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Figure 42 is an example of the code required to add the terminal to 
the input stack as the current input source. In this example, the 
execute form of the STACK macro instruction is used to build the Input 
Output Parameter list for you. The list form of the STACK macro 
instruction expands into a STACK Parameter Block, and its address is 
passed to the execute form of the macro instruction as the PARM operand 
address. 



Figure 42. Coding Example -- STACK Specifying the Terminal as the Input 
Source 


This sequence of code does not make use of the IKJCPPL DSECT to 
access the Command Processor Parameter List, nor does it provide 
reenterable code. 
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Building the List: Source Descriptor (LSD) 


A List Source Descriptor (LSD) is a four word control block which 
describes the in-storage list pointed to by the new element you are 
adding to the Input Stack. If you are designating the Terminal as the 
input source # no LSD is necessary and the second word of the STPB will 
be zero. If you specify STORAGE as the input source in the STACK macro 
instruction, your code must build an LSD, and place a pointer to it as a 
sublist of the STORAGE operand. The LSD must begin on a double word 
boundary, and must be created in the shared subpool designated by the 
Terminal Monitor Program; the IBM-supplied TMP shares subpool 78 with 
the Command Processors. The LSD is defined by the IKJLSD DSECT. Figure 
43 describes the contents of the LSD. 


1 T 1 

Number of | 

Bytes | Field 

j 

r i 

Contents or Meaning 

4 | LSDADATA 

j i 

The address of the in-storage list. 

2 | LSDRCLEN 

1 

1 

1 

The record length if the in-storage list 
contains fixed length records. Zero if the 
record lengths are variable. 

1 - 1 

2 | LSDTOTLN 

1 

1 

The total length of the in-storage list; the 
sum of the lengths of all records in the 
list. 

|_ 

4 | LSDANEXT 

1 

l 

1 

1 

J. j | 

Pointer to the next record to be processed. 
Initialize this field to the address of the 
first record in the list. The field is 
updated by the GETLINE and PUTGET service 
routines. 

4 | LSDRSVRD 

Reserved 


L- JL - JL -J 

Figure 43. The List Source Descriptor 


If you have provided an LSD, and specified the STORAGE operand in the 
STACK macro instruction, the second word of the Stack Parameter Block 
will contain the address of the LSD, and the STACK control block 
structure will look like Figure 44. 
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Figure 44. STACK Control Blocks: In-Storage List Specified 
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Figure 45 is an example of the code required to use the STACK macro 
instruction to place a pointer to an in-storage list on the input stack. 


In the example, the GETMAIN macro instruction is used to obtain 
storage in subpool 7 8 for the List Source Descriptor and the in-storage 
list itself. The execute form of the STACK macro instruction 
initializes the Input Output Parameter List required by the STACK 
service routine. The list form of the STACK macro instruction expands 
into a STACK Parameter Block, and its address is passed to the STACK 
service routine via the PARM operand in the execute form of the STACK 
macro instruction. 


IQIIBaBSISSSSISlS^SISSSSSSISSSZISZSIBISSSDSSSSI^SiaSSBElBSSSII 
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Figure 45. Coding Example — STACK Specifying an In-Storage List as the 
Input Source (Part 1 of 3) 
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Figure 45. Coding Example -- STACK Specifying an In-Storage List as the 
Input Source (Part 2 of 3) 
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Figure 45. Coding Example — STACK Specifying an In-Storage List as the 
Input Source (Part 3 of 3) 
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Return Codes From STACK 


When it returns to the program which invoked it, the STACK Service 
Routine will provide one of the following return codes in general 
register fifteen: 

Code Meaning 

0 STACK has completed sucessfully 

4 One or more of the parameters passed 

to STACK were invalid. 


GETLINE - GETTING A LINE OF INPUT 

You use the GETLINE macro instruction to obtain all input lines other 
than commands or subcommands, and PROMPT message responses. Commands, 
subcommands, and PROMPT message responses should be obtained with the 
PUTGET macro instruction. 


When a GETLINE macro instruction is executed, a line is obtained from 
the current source of input - the terminal or an in-storage list - or 
optionally, from the terminal, regardless of the current source of 
input. The processing of the input line varies according to several 
factors. Included in these factors are the source of input, and the 
options you specify for logical or physical processing of the input 
line. The GETLINE Service Routine determines the type of processing to 
be performed from the operands coded in the GETLINE macro instruction, 
and returns a line of input. 

This topic describes: 

• The list and execute forms of the GETLINE macro instruction. 

• The sources of input. 

• The GETLINE Parameter Block. 

• The input line format. 

• Examples of GETLINE. 

• Return codes from GETLINE. 
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The GETLINE Macro Instruction - List Form 


The list form of the GETLINE macro instruction builds and initializes a 
GETLINE Parameter Block (GTPB) # according to the operands you specify in 
the GETLINE macro. The GETLINE Parameter Block indicates to the GETLINE 
service routine which functions you want performed. Figure 46 shows the 
list form of the GETLINE macro instruction; each of the operands is 
explained following the figure. Appendix B describes the notation used 
to define macro instructions. 


r~ 

. . . ■■ ■ x 

T" 

P — — — — —— 


T 


[symbol] | 

GETLINE | 

INPUT=((ISTACK) 

(.LOGICAL l) 

l 


i 

i 

i 

i 

\term / 

Uphysical! J 

1 

1 


i 

i 

I 

i 

[",T ERMGET= (( EDIT ) 

If, WAIT ))1,MF=L 

1 

1 

i_ 

i 

-L 

_1 

[ (ASIS) 

1 NOWAIT/ J 

1 

j 


Figure 46. The List Form of the GETLINE Macro Instruction 
INPUT= 

Indicates that an input line is to be obtained. That input line is 
further described by the INPUT sublist operands ISTACK, TERM, 
LOGICAL, and PHYSICAL. ISTACK and LOGICAL are the default values. 

ISTACK 

Obtain an input line from the currently active input source 
indicated by the input stack. 


TERM 

Obtain an input line from the terminal. If TERM is coded in the 
macro instruction, the input stack is ignored and regardless of the 
currently active input source, a line is returned from the 
terminal. 

LOGICAL 

The input line to be obtained is a logical line; the GETLINE 
service routine is to perform logical line processing. 

PHYSICAL 

The input line to be obtained is a physical line. The GETLINE 
service routine need not inspect the input line. 

NOTE: If the input line you are requesting is a Logical line 

coming from the input source indicated by the input stack, you need 
not code the INPUT operand or its sub-list operands. The input 
line description defaults to ISTACK, LOGICAL. 

TERMGET 

Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal, this operand indicates 
to the TGET SVC which of the TGET options to use. The TGET options 
are EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT 
and WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS) , the 
buffer is to be filled out with trailing blanks. 
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ASIS 


Specifies that minimal editing is to be done as follows: 

a. Transmission control characters are removed. 

b. The line of input is translated from terminal code to EBCDIC. 

c. Line deletion and character deletion editing is performed. 

d. Line feed and carriage return characters, if present, are 
removed. 

WAIT 

Specifies that control is to be returned to the routine that issued 
the GETLINE macro instruction only after an input message has been 
read. 

NOWAIT 

Specifies that control is to be returned to the routine that issued 
the GETLINE macro instruction whether or not a line of input is 
available. If a line of iiiput is not: available, a return code of 
12 decimal is returned in register 15 to the command processor. 


MF=L 

Indicates that this is the list form of the macro instruction. 
NOTE : In the list form of the macro instruction, only 


r - 1 

| GETLINE MF=L | 

L-J 


is required. The other operands and their sublists are optional because 
they may be supplied by the execute form of the macro instruction, or 
automatically supplied if you want the default values: 

flNPUT=( ( ISTACK 1 (, LOGICAL )) ] 

| (TERM )\, PHYSICAL/ j 

i i 

j and j 

I I 

|,TERMGET =(( EDIT \ I , WAIT )) j 

j \ASISn# N 0 W AiT) j 

L -J 


The operands you specify in the list form of the GETLINE macro 
instruction set up control information used by the GETLINE service 
routine. The INPUT= and TERMGET= operands set bits in the GETLINE 
Parameter Block to indicate to the GETLINE service routine which options 
you want performed. 
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The GETLINE Macro Instruction - Execute Form 


Use the execute form of the GETLINE macro instruction to perform the 
following three functions: 

1. You may use it to set up the Input Output Parameter List (IOPL). 

2. You may use it to initialize those fields of the GETLINE Parameter 
Block (GTPB) not initialized by the List form of the macro 
instruction, or to modify those fields already initialized. 

3. You use it to pass control to the GETLINE service routine which 
gets the line of input* 

Figure 47 shows the execute form of the GETLINE macro instruction; 
each of the operands is explained following the figure. Appendix B 
describes the notation used to define macro instructions. 


( 

1 

T 

— 

— 1 

| (symbol] 

1 

I 

GETLINE |[PARM=parameter 

i 

address][,UPT=upt address] 

i 
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1 

1 

1 

|[,ECT=ect address][,ECB=ecb address] 

1 

1 

i 

i 


1 

1 

||,INPUT=((ISTACK 

(.LOGICAL \)"| 

i 

i 


1 

1 

| L \TERM 

1 

f (, PHYSICAL) J 

i 

i 


1 

1 

| [,TERMGET=C (EDIT 
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i 
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1 

1 

j L \ASIS 

1 

UnowaitJ J 

i 
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1 
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Figure 47. The Execute Form of the GETLINE Macro Instruction 


PARM=parameter address 

Specifies the address of the 2-word GETLINE Parameter Block (GTPB). 
It may be the address of a list form GETLINE macro instruction. 

The address is any address valid in an RX instruction, or the 
number of one of the general registers 2-12 enclosed in 
parentheses. This address will be placed in the Input Output 
Parameter List (IOPL). 

UPT=upt address 

Specifies the address of the User Profile Table (UPT). You may 
obtain this address from the Command Processor Parameter List 
pointed to by register one when the command processor is attached 
by the Terminal Monitor Program. The address may be any address 
valid in an RX instruction or the number of one of the general 
registers 2-12 enclosed in parentheses. This address will be 
placed in the IOPL. 

ECT=ect address 

Specifies the address of the Environment Control Table (ECT). You 
may obtain this address from the CPPL pointed to by register 1 when 
the Command Processor is attached by the Terminal Monitor Program. 
The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in 
parentheses. This address will be placed into the IOPL. 
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ECB=ecb address 

Specifies the address of an Event Control Block (ECB). You must 
provide a one-word Event Control Block and pass its address to the 
GETLINE Service Routine by placing it into the IOPL. The address 
may be any address valid in an RX instruction or the number of one 
of the general registers 2-12 enclosed in parentheses. This 
address will be placed into the IOPL. 

INPUT= 

Indicates that an input line is to be obtained. This input line is 
further described by the INPUT sublist operands ISTACK, TERM, 
LOGICAL, and PHYSICAL. ISTACK and LOGICAL are the default values. 

ISTACK 

Obtain an input line from the currently active input source 
indicated by the input stack. 

TERM 

Obtain an input line from the terminal. If TERM is coded in the 
macro instruction, the input stack will be ignored and regardless 
of the currently active input source, a line is returned from the 
terminal. 

LOGICAL 

The input line to be obtained is a logical line; the GETLINE 
service routine is to perform logical line processing. (see 
Glossary for the definition of "logical line.") 

PHYSICAL 

The input line to be obtained is a physical line. The GETLINE 
service routine need not inspect the input line. 

NOTE: If the input line you are requesting is a Logical line 

coming from the input source indicated by the input stack, you need 
not code the INPUT operand or its sublist operands. The input line 
description defaults to ISTACK, LOGICAL. 

TERMGET 

Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal, this operand indicates 
to the TGET SVC which of the TGET options to use. The TGET options 
are EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT 
and WAIT. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the input 
buffer is to be filled out with trailing blanks. 

ASIS 

Specifies that minimal editing is to be done by the TGET SVC. The 
following editing functions will be performed by TGET: 

a. Transmission control characters are removed. 

b. The line of input is translated from terminal code to EBCDIC. 

c. Line deletion and character deletion editing are performed. 

d. Line feed and carriage return characters, if present, are 
removed. 

WAIT 

Specifies that control is to be returned to the routine that issued 
the GETLINE macro instruction, only after an input message has been 
read. 
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NOWAIT 

Specifies that control is to be returned to the routine that issued 
the GETLINE macro instruction whether or not a line of input is 
available. If a line of input is not available, a return code of 
12 decimal is returned in register 15 to the command processor. 


ENTRY=entry address or (15) 

Specifies the entry point of the GETLINE service routine. If ENTRY 
is omitted, a LINK macro instruction will be generated to invoke 
the GETLINE service routine. The address may be any address valid 
in an RX instruction or (15) if the entry point address has been 
loaded into general register 15. 


MF=E 

Indicates that this is the execute form of the macro instruction. 


listaddr 

( 1 ) 

The address of the 4-word Output Parameter List (I0PL). This may 
be a completed IOPL that you have built, or it may be 4 words of 
declared storage that will be filled from the PARM f UPT f ECT # and 
ECT operands of this execute form of the GETLINE macro instruction. 
The address is any address valid in an RX instruction or (1) if the 
parameter list address has been loaded into general register 1. 


NOTE : In the execute form of the GETLINE macro instruction only the 

following is required: 

r-7-7- t 

|GETLINE MF=(E,(list address)) | 

| 1 ( 1 ) / | 

L-.-J 

The PARM=, UPT=, ECT=, and ECB= operands are not required if you have 
built your IOPL in your own code. 

The other operands and their sublists are optional because you may have 
supplied them in the list form of the macro instruction or in a previous 
execution of GETLINE, or because you are using the default values: 

i-1 

|INPUT= ((I STACK U, LOGICAL )) | 

| (TERM /(,PHYSICAL) j 

I I 

| and | 

I I 

|TERMGET=((EDIT) L WAIT )) | 

| (ASISJ (, NOWAIT f j 

L-J 

The ENTRY= operand need not be coded in the macro instruction. If it is 
not, a LINK macro instruction will be generated to invoke the I/O 
service routine. 

The operands you specify in the execute form of of the GETLINE macro 
instruction are used to set up control information used by the GETLINE 
Service Routine. You can use the PARM=, UPT=, ECT=, and ECB= operands 
of the GETLINE macro instruction to build, complete, or modify an IOPL. 
The INPUT= and TERMGET= operands set bits in the GETLINE Parameter 
Block. These bit settings indicate to the GETLINE Service Routine which 
options you want performed. 
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Sources of Input 


There are two sources of input provided; they are the terminal and an 
in-storage list. 

TERMINAL : Input comes from the terminal under either of the following 

conditions: 

• You have specified the terminal as the input source by including the 
TERM operand in the GETLINE macro instruction. 

• You have specified the current element of the Input Stack by 
including the ISTACK operand in the GETLINE macro instruction, and 
the current element is a terminal element. 

If you specify terminal as the input source, you have the option of 
requesting the GETLINE Service Routine to process the input as a logical 
or physical line by including the LOGICAL or the PHYSICAL operand in the 
macro instruction. LOGICAL is the default value. 

Physical Line Processing : A physical lint; is a line which is returned 
to the requesting program exactly as it is received from the input 
source. The contents of the line are not inspected by the GETLINE 
service routine. 

Logical Line Processing : A logical line is a line which has had 
additional processing by the GETLINE service routine before it is 
returned to the requesting program. If logical line processing is 
requested, each line returned to the routine that issued the GETLINE is 
inspected to see if the last character of the line is a continuation 
mark (a dash •-•). A continuation mark signals GETLINE to get another 
line from the terminal and to concatenate that line with the line 
previously obtained. The continuation mark is overlaid with the first 
character of the new line. 

IN-STORAGE LIST : If the top element of the input stack is an in-storage 
list, and you do not specify TERM in the GETLINE macro instruction, the 
line will be obtained from the in-storage list. The in-storage list is 
a resident data set which has been previously made available to the I/O 
service Routines with the STACK Service Routine. No logical line 
processing is performed on the lines because it is assumed that each 
line in the in-storage list is a logical line. It is also assumed that 
no single record has a length greater than 256 bytes. 

End of Data Processing 

If you issue a GETLINE macro against an in-storage list from which all 
the records have already been read, GETLINE senses an end of data (EOD) 
condition. GETLINE deletes the top element from the Input Stack and 
passes a return code of 16 in register 15. Return code 16 indicates 
that no line of input has been returned by the GETLINE service routine. 
You can use this EOD code (16) as an indication that all input from a 
particular source has been exhausted and no more GETLINE macro 
instructions should be issued against this input source. If you reissue 
a GETLINE macro instruction against the input stack after a return code 
of 16, a record will be returned from the next input source indicated by 
the input STACK. You can identify the source of this record by the 
return code (0 = terminal, 4 = in-storage). 

Building the GETLINE Parameter Block 

When the list form of the GETLINE macro instruction expands, it builds a 
two word GETLINE Parameter Block (GTPB)• The list form of the macro 
instruction initializes this GTPB according to the operands you have 
coded in the macro instruction. This initialized block, which you may 
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later modify with the execute form of the macro instruction, indicates 
to the GETLINE Service Routine the function you want performed. 

You must supply the address of the GTPB to the Execute form of the 
GETLINE macro instruction. For non-reenterable programs you can do this 
simply by placing a symbolic name in the symbol field of the list form 
of the macro instruction, and passing this symbolic name to the execute 
form of the macro instruction as the PARM value. The GETLINE Parameter 
Block is defined by the IKJGTPB DSECT. Figure 48 describes the contents 
of the GTPB. 


Number of 
Bytes 


Field 


Contents or Meaning 


Byte 
.. 0 . ■ 
. . 1 . . 
...0 . 


. ..1 


xx. 


xxxx 


Byte 2 
xxxx xxxx 


Control flags. These bits describe the 
requested input line to the GETLINE service 
routine. 

The input line is a logical line. 

The input line is a physical line. 

The input line is to be obtained from the 
current input source indicated by the input 
stack. 

The input line is to be obtained from the 
terminal. 

Reserved bits. 


Reserved. 


Byte 1 

1 ... .... 
...0 .... 




. ..00 


,.01 


.xx. xx.. 

Byte 2 
xxxx xxxx 


TGET options field. These bits indicate to 
the TGET SVC which of the TGET options you 
want to use. 

Always set to 1 for TGET. 

WAIT processing has been requested. Control 
will be returned to the issuer of GETLINE 
only after an input message has been read. 
NOWAIT processing has been requested. 

Control will be returned to the issuer of the 
GETLINE macro instruction whether or not a 
line of input is available. 

EDIT processing has been requested. In 
addition to the editing provided by ASIS 
processing, the input buffer is to be filled 
out with training blanks to the next 
double-word boundary. 

ASIS processing has been requested. (See the 
ASIS operand of the GETLINE macro instruction 
description). 

Reserved bits. 


Reserved. 




GTPBIBUF 


__L_X_ 

The GETLINE Parameter Block 


The address of the input buffer. The GETLINE 
service routine fills this field with the 
address of the input buffer in which the 
input line has been placed. 


Figure 48. 
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Input Line Format - The Input Buffer 


The second word of the GETLINE Parameter Block contains zeros until the 
GETLINE service routine returns a line of input. The service routine 
places the requested input line into an input buffer beginning on a 
double word boundary located in subpool 1. It then places the address 
of this input buffer into the second word of the GTPB. The input buffer 
belongs to the command processor that issued the GETLINE macro 
instruction. The buffers returned by GETLINE are automatically freed 
when your C.P. relinquishes control. If space is a consideration, you 
should free the input buffer with the FREEMAIN macro instruction after 
you have processed or copied the input line. 

Regardless of the source of input, an in-storage list or the 
terminal, the input line returned to the command processor by the 
GETLINE Service Routine is in a standard format. All input lines are in 
a variable length record format with a full-word header followed by the 
text returned by GETLINE. Figure 49 shows the format of the input 
buffer returned by the GETLINE service routine. 



Figure 49. Format of the GETLINE Input Buffer 

The two-byte length field contains the length of the input line 
including the header length (4 bytes). You can use this length field to 
determine the length of the input line to be processed, and later, to 
free the input buffer with the R form of the FREEMAIN macro instruction. 

The two-byte offset field is always set to zero on return from the 
GETLINE Service Routine. 

Figure 50 shows the GETLINE control block structure after the GETLINE 
Service Routine has returned an input line. 
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Figure 50. GETLINE Control Blocks - Input Line Returned 
Examples of GETLINE 

Figure 51 is an example of the code required to execute the GETLINE 
macro instruction. In this example two execute forms of the GETLINE 
macro instruction are issued. The first one builds the IOPL, and uses 
the parameters initialized by the list form of the macro instruction to 
get a physical line from the terminal with the NOWAIT and ASIS options. 

In the second execution of the GETLINE macro instruction, the same 
IOPL is used, but the GETLINE options are changed from TERM to ISTACK, 
and from NOWAIT to WAIT explicitly, and from PHYSICAL to LOGICAL and 
from ASIS to EDIT by default. 

Notice also that the IKJCPPL DSECT is used to map the Command 
Processor Parameter List, and the IKJGTPB DSECT is used to map the 
GETLINE Parameter Block. 
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Figure 51. Coding Example -- Two Executions of GETLINE (Part 1 of 2) 
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Figure 51. Coding Example — Two Executions of GETLINE (Part 2 of 2) 
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Return Codes from GETLINE 


When it returns to the program that invoked it, the GETLINE service 
routine returns one of the following codes in general register fifteen: 

CODE MEANING 

0 GETLINE has completed successfully. The line was obtained 

from the terminal. 

4 GETLINE has completed successfully. The line was returned 

from an in-storage list* 

8 The GETLINE function was not completed. An attention 

interruption occurred during GETLINE processing, and the 
user's attention routine turned on the completion bit in the 
communications ECB. 

12 The NOWAIT option was specified and no line was obtained. 

16 eod - An attempt was made to get a line from an in-storage 

list but the list had been exhausted. 

20 Invalid parameters passed to the GETLINE Service Routine. 

24 A conditional GETMAIN was issued by GETLINE for input 

buffers and there was not sufficient space to satisfy the 
request. 


PUTLINE - PUTTING A LINE OUT 1 TO THE TERMINAL 

Use the PUTLINE macro instruction to prepare a line and write it to the 
terminal. Use PUTLINE to put out lines that do not require immediate 
response from the terminal; use PUTGET to put out lines that require 
immediate response. The types of lines which do not require response 
from the terminal are defined as data lines and informational message 
lines. 

The PUTLINE service routine prepares a line for output according to 
the operands you code into the list and execute forms of the PUTLINE 
macro instruction. The operands of the macro instruction indicate to 
the PUTLINE service routine the type of line being put out (data line or 
informational message line), the type of processing to be performed on 
the line (format only, second level informational message chaining, text 
insertion), and the TPUT options requested. 

This topic describes: 


• The list and execute forms of the PUTLINE macro instruction. 

• The PUTLINE Parameter Block. 

• The types and formats of output lines. 

• PUTLINE message processing. 

• Return codes from PUTLINE. 

Coding examples are included where needed. 
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The PUTLINE Macro Instruction - List Form 


The list form of the PUTLINE macro instruction builds and initializes a 
PUTLINE Parameter Block (PTPB) f according to the operands you specify in 
the macro instruction. The PUTLINE Parameter Block indicates to the 
PUTLINE service routine which functions you want performed. Figure 52 
shows the list form of the PUTLINE macro instruction; each of the 
operands is explained following the figure. Appendix B describes the 
notation used to define macro instructions. 


[symbol]| PUTLINE 


f (, SINGLE ) 1| 

OUTPUT= (output address L TERM W ,MULTLVL W, INFORM) || 
L U FORMAT/ (, MULTLIN ) DATA / Jj 

[ ( edit ) 1 

, TERMPUT= ( \ASIS > /. WAIT )/, NOHOLD ) /, NOBREAK I) 

(CONTROL) (, NOWAIT f\ 9 HOLD f l,BREAKINJ J 


,MF=L 

L _J. _JL. 

Figure 52. The List Form of the PUTLINE Macro Instruction 


L_ ± _J_J 


OUTPUT=output address 

Indicates that an output line is to be written to the terminal. 
The type of line provided and the processing to be performed on 
that line by the PUTLINE service routine are described by the 
OUTPUT sublist operands TERM, FORMAT, SINGLE, MULTLVL, MULTLIN, 
INFOR and DATA. The default values are TERM, SINGLE, and INFOR. 


The output address differs depending upon whether the output line 
is an informational message or a data line. For DATA requests, it 
is the address of the beginning (the full-word header) of a data 
record to be written to the terminal. For informational message 
requests (INFOR), it is the address of the Output Line Descriptor. 
The Output Line Descriptor (OLD) describes the message to be put 
out, and contains the address of the beginning (the full-word 
header) of the message or messages to be written to the terminal by 
the PUTLINE Service Routine. 


TERM 

Write the line out to the terminal. 


FORMAT 

The output request is only to format a single message and not to 
put the message out to the terminal. The PUTLINE Service Routine 
returns the address of the formatted line by placing it in the 
third word of the PUTLINE Parameter Block. 


SINGLE 

The output line is a single line. 


MULTLVL 

The output message consists of multiple levels. INFOR must be 
specified. 


MULTLIN 

The output 
specified. 

INFOR 

The output 


data consists of multiple lines. 


line is an informational message. 


DATA must be 
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DATA 


The output line is a data line. 

TERMPUT 

Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal, this operand indicates which of the 
TPUT options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL, WAIT or NOWAIT, NCHOLD or HOLD, and NOBREAK or BREAKIN. 

The default values are EDIT, WAIT, NOHOLD, and NOBREAK. 


EDIT 

Specifies that in addition to minimal editing (see ASIS), the 

following TPUT functions are requested: 

a. Any trailing blanks are removed before the line is written to 
the terminal. If a blank line is sent, the terminal vertically 
spaces one line. 

b. Control characters are added to the end of the output line to 
position the carrier to the beginning of the next line. 

c. All terminal control characters (for example: bypass, restore, 
horizontal tab, new line) are replaced with a printable 
character. "Backspace" is an exception; see (d.) under ASIS. 

ASIS 

Specifies that minimal editing is to be performed by TPUT as 

follows: 

a. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to 
prevent program caused I/O errors. This does not mean that all 
unprintable characters are eliminated. "Restore", "upper 
case", "lower case", "bypass", and "bell ring", for example, 
might be valid but nonprinting characters at some terminals. 
(See CONTROL). 

b. Transmission control characters are added. 

c. EBCDIC "NL", placed at the end of the message, indicates to the 
TPUT SVC that the carrier is to be returned at the end of the 
line. "NL" is replaced with whatever is necessary for that 
particular terminal type to cause the carrier to return. This 
"NL" processing occurs only if you specify ASIS, and the "NL" 
is the last character in your message. 

If you specify EDIT, "NL" is handled as described in (c.) 
under EDIT. 

If the "NL" is embedded in your message, it is sent to the 
terminal as a carriage return. No idle characters are added 
(see f. below). This may cause overprinting, particularly on 
terminals that require a line-feed character to position the 
carrier on a new line. 

d. If you have used "backspace" in your output message, but the 
"backspace" character does not exist on the terminal type to 
which the message is being routed, TPUT attempts alternate 
methods to accomplish the backspace. 
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e. Control characters are added as needed to cause the message to 
occur on several lines if the output line is longer than the 
terminal line size. 

f. Idle characters are sent at the end of each line to prevent 
typing as the carrier returns. 

CONTROL 

Specifies that the output line is composed of terminal control 
characters and will not print or move the carrier on the terminal. 
This option should be used for transmission of characters such as 
"bypass", "restore", or "bell ring". 


WAIT 

Specifies that control will not be returned until the output line 
has been placed into a terminal output buffer. 

NOWAIT 

Specifies that control should be returned whether or not a terminal 
output buffer is available. If no buffer is available, a return 
code of 8 (decimal) will be returned in register 15, to the Command 
Processor. 

NOHOLD 

Specifies that the control is to be returned to the routine that 
issued the PUTLINE macro instruction, and that routine can continue 
processing as soon as the output line has been placed on the output 
queue. 


HOLD 

Specifies that the routine that issued the PUTLINE macro 
instruction cannot continue its processing until this output line 
has been put out to the terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he 
is not to be interrupted. The output message is placed on the 
output queue to be printed after the terminal user has completed 
the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at 
the terminal is transmitting, he is interrupted, and this output 
line is sent. Any data that was received before the interruption 
is kept and displayed at the terminal following this output line. 


MF=L 

Indicates that this is the list form of the macro instruction. 

Note : In the list form of the macro instruction, only the following is 

required: 

r- 1 

|PUTLINE MF=L | 

L-J 

The output line address is required for each issuance of the PUTLINE 
macro instruction but it may be supplied in the execute form of the 
macro instruction: 

r- 1 

|OUTPUT=(output address) | 

L-J 
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The other operands and sublists are optional because you can supply 
them in the execute form of the macro instruction, or they may be 
supplied by the macro expansion if you want the default values: 


OUTPUT=( 


and 


( f TERM ) ( , SINGLE ) j, INFOR ) ) 
\, FORMAT/ < , MULTLVL > DATA / 

(,multlin) 


, TERMPUT=(( EDIT ) /, WAIT \ /, NO HOLD \ (, NOBREAK )) 

< as is >(, nowait/ (, hold /(,breakin/ 

(control) 


The operands you specify in the list form of the PUTLINE macro 
instruction set up control information used by the PUTLINE service 
routine. This control information is passed to the PUTLINE service 
routine in the PUTLINE Parameter Block, a three word parameter block 
built and initialized by the list ^^ j -' u ^ TvnrnT ■ 


The PUTLINE Macro Instruction - Execute Form 


Use the execute form of the PUTLINE Macro instruction to put a line or 
lines out to the terminal, to chain second level messages, and to format 
a line and return the address of the formatted line to the code that 
issued the PUTLINE macro instruction. The execute form of the PUTLINE 
macro instruction performs the following functions: 

1. It can be used to set up the Input Output Parameter List (IOPL)• 

2. It can be used to initialize those fields of the PUTLINE Parameter 
Block (PTPB) not initialized by the List form of the macro 
instruction, or to modify those fields already initialized. 

3. It passes control to the PUTLINE service routine. 

The PUTLINE Service Routine makes use of the IOPL and the PTPB to 
determine which of the PUTLINE functions you want performed. 
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Figure 53 shows the execute form of the PUTLINE macro instruction; 
each of the operands is explained following the figure. Appendix B 
describes the notation used to define macro instructions. 



[PARM= parameter address] [,UPT=upt address] 
[,ECT=ect address] [. f ECB=ecb address] 


,OUTPUT=(output address (. TERM ) (. SINGLE 

{,FORMAT/ <,MULTLVL 
I.MULTLIN 


/. TERM ) (,j 

{.FORMAT/ 

If] 

(. INFOR ) )I 

{.data / J 


( EDIT j 

,TERMPUT=(<ASIS > / . WAIT ) /. NOHOLD )/. NOBREAK )) 
(control) {.NOWAIT/ {.HOLD /{.BREAKINJ 


r ENTRY=/entry address 
1 (15) 


\] , MF= (E,/ li 

;J 


list address)) 


Figure 53. The Execute Form of the PUTLINE Macro Instruction 


PARM=parameter address s 

Specifies the address of the 2-word PUTLINE Parameter Block (PTPB). 
It may be the address of a List form PUTLINE macro instruction. 

The address is any address in an RX instruction, or the number of 
one of the general registers 2-*12 enclosed in parentheses. This 
address will be placed into the IOPL. 


UPT=upt address 

Specifies the address of the User Profile Table (UPT). You may 
obtain this address from the Command Processor Parameter List 
(CPPL) pointed to by register one when a Command Processor is 
attached by the Terminal Monitor Program. The address may be any 
address valid in an RX instruction or it may be placed in one of 
the general registers 2-12 and the register number enclosed in 
parentheses. This address will be placed into the IOPL. 


ECT=ect address 

Specifies the address of the Environment Control Table (ECT). You 
may obtain this address from the CPPL pointed to by register 1 when 
a command processor is attached by the Terminal Monitor Program. 

The address may be any address valid in an RX instruction or it may 
be placed in one of the general registers 2-12 and the register 
number enclosed in parentheses. This address will be placed into 
the IOPL. 


ECB=ecb address 

Specifies the address of the Event Control Block (ECB)• You must 
provide a one-word event Control Block and pass its address to the 
PUTLINE service routine. This address will be placed into the 
IOPL. The address may be any address valid in an RX instruction or 
it may be placed in one of the general registers 2-12 and the 
register number enclosed in parentheses. 
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OU T P UT=out put address 

Indicates that an output line is provided. The type of line 
provided and the processing to be performed on that line by the 
PUTLINE service routine are described by the OUTPUT sublist 
operands TERM, FORMAT, SINGLE MULTLVL, MULTLIN, INFOR and DATA. 

The default values are TERM, SINGLE, and INFOR. 

The output address differs depending upon whether the output line 
is an informational message or a data line. For DATA requests, it 
is the address of the beginning (the full-word header) of a data 
record to be put out to the terminal. For informational message 
requests (INFOR), it is the address of the Output Line Descriptor. 
The Output Line Descriptor (OLD) describes the message to be put 
out, and contains the address of the beginning (the full-word 
header) of the message or messages to be written to the terminal by 
the PUTLINE service routine. 


TERM 

Write the line out to the terminal. 


FORMAT 

The output request is only to format a single message and not to 
put the message out to the terminal. The PUTLINE service routine 
returns the address of the formatted line by placing it in the 
third word of the PUTLINE Parameter Block. 

SINGLE 

The output line is a single line. 

MULTLVL 

The output message consists of multiple levels. INFOR must be 
specified. 

MULTLIN 

The output data consists of multiple lines. DATA must be 
specified. 

INFOR 

The output line is an informational message. 

DATA 

The output line is a data line. 

TERMPUT 

Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal, this operand indicates which of the 
TPUT options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL, WAIT or NOWAIT, NOHOLD or HOLD, and NOBREAK or BREAKIN. 

The default values are EDIT, WAIT, NOHOLD, and NOBREAK. 

EDIT 

Specifies that in addition to minimal editing (see ASIS), the 
following TPUT functions are requested: 

a. Any trailing blanks are removed before the line is written to 
the terminal. If a blank line is sent the terminal vertically 
spaces one line. 

b. Control characters are added to the end of the output line to 
position the carrier to the beginning of the next line. 

c. All terminal control characters (for example: bypass, restore, 
horizontal tab, new line) are replaced with a printable 
character. "Backspace" is an exception; see (d.) under ASIS. 
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ASIS 


Specifies that minimal editing is to be performed by TPUT as 

follows: 

a. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to 
prevent program-caused I/O errors. This does not mean that all 
unprintable characters are eliminated. "Restore", "upper 
case", "lower case", "bypass", and "bell ring", for example, 
may be valid but nonprinting characters at some terminals. 

(See CONTROL). 

b. Transmission control characters are added. 

c. EBCDIC "NL", placed at the end of the message, indicates to the 
TPUT SVC that the carrier is to be returned at the end of the 
line. "NL" is replaced with whatever is necessary for that 
particular terminal type to cause the carrier to return. This 
"NL" processing occurs only if you specify ASIS, and the "NL" 
is the last character in your message. 

If you specify EDIT, "NL" is handled as described in (c.) 
under EDIT. 

If the "NL" is embedded in your message, a semicolon is 
substituted for "NL" and sent to the terminal. No idle 
characters are added (see f. below). This may cause 
overprinting, particularly on terminals that require a 
line-feed character to position the carrier on a new line. 

d. If you have used "backspace" in your output message, but the 
"backspace" character does not exist on the terminal type to 
which the message is being routed, the PUTLINE service routine 
attempts alternate methods to accomplish the backspace. 

e. Control characters are added as needed to cause the message to 
occur on several lines if the output line is longer than the 
terminal line size. 

f. Idle characters are sent at the end of each line to prevent 
typing as the carrier returns. 

CONTROL 

Specifies that the output line is composed of terminal control 

characters and will not print or move the carrier on the terminal. 

This option should be used for transmission of characters such- as 

"bypass", "restore", or "bell ring". 


WAIT 

Specifies that control will not be returned until the output line 
has been placed into a terminal output buffer. 

NOWAIT 

Specifies that control should be returned whether or not a terminal 
output buffer is available. If no buffer is available, a return 
code of 8 (decimal) is returned in register 15. 

NOHOLD 

Specifies that control is returned to the routine that issued the 
PUTLINE macro instruction, and it can continue processing, as soon 
as the output line has been placed on the output queue. 
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HOLD 


Specifies that the module that issued the PUTLINE macro instruction 
is not to resume processing until the output line has been put out 
to the terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he 
is not to be interrupted. The output message is placed on the 
output queue to be printed after the terminal user has completed 
the line. 

BREAKIN 

Specifies that output has precendence over input. If the user at 
the terminal is transmitting, he is interrupted, and the output 
line is sent. Any data that was received before the interruption 
is kept and displayed at the terminal following the output line. 

ENTRY=entry address or (15) 

Specifies the entry point of the PUTLINE service routine. If ENTRY 
is omitted, the PUTLINE macro expansion will generate a LINK macro 
instruction to invoke the PUTLINE service routine. The address may 
be any address valid in an RX instruction or (15) if the entry 
point address has been loaded into general register 15. 


MF=E 

Indicates that this is the execute form of the PUTLINE macro 
instruction. 

list address 
(1) 

The address of the 4-word Input Output Parameter List (IOPL). This 
may be a completed IOPL that you have built, or 4 words of declared 
storage to be filled from the PARM, UPT, ECT, and ECB operands of 
this execute form of the PUTLINE macro instruction. The address is 
any address valid in an RX instruction or (1) if the parameter list 
address has been loaded into general register 1. 

Note : In the execute form of the PUTLINE macro instruction only the 

following is required: 

r 

|PUTLINE MF=(E, /list address\) j 

I i Cl) / | 

L-J 

The PARM=, UPT=, ECT=, and ECB= operands are not required if you have 
built your IOPL in your own code. 

The output line address is required for each issuance of the PUTLINE 
macro instruction, but you may supply it in the list form of the macro 
instruction: 


jOUTPUT=(output address) 

L_ 


I 

I 

—I 
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The other operands and sublists are optional because you may have 
supplied them in the list form of the macro instruction or in a previous 
execute form, or because you may want to use the default values which 
are automatically supplied by the macro expansion itself. The other 
operands and sublists ares 


r- 1 

| (, SINGLE ) I 

| OUTPUT= ( TERM ) /,MULTLVL } /, INFOR\) | 


I (,FORMAT/ (,MULTLIN)\,DATA / 

| and 

I 

I (edit 

I ,TERMPUT=(<ASIS 

I (control 

L_ 

The ENTRY= operand need not be coded in the macro instruction. If it 
is not, a LINK macro instruction will be generated by the macro 
expansion to invoke the I/O service routine. 

The operands you specify in the execute form of the PUTLINE macro 
instruction set up control information used by the PUTLINE service 
routine. You can use the PARM=, UPT=, ECT=, and ECB=, operands of the 
PUTLINE macro instruction to build, complete or modify an IOPL. The 
OUTPUT= and TERMPUT= operands and their sublist operands initialize the 
PUTLINE Parameter Block. The PUTLINE Parameter Block is referenced by 
the PUTLINE Service Routine to determine which functions you want 
PUTLINE to perform. 

Building the PUTLINE Parameter Block 

When the list form of the PUTLINE macro instruction expands, it builds a 
three-word PUTLINE Parameter Block (PTPB). The list form of the macro 
instruction initializes the PTPB according to the operands you have 
coded in the macro instruction. The initialized block, which you may 
later modify with the execute form of the PUTLINE macro instruction, 
indicates to the PUTLINE service routine the function you want 
performed. 

You must supply the address of the PTPB to the execute form of the 
PUTLINE macro instruction- Since the list form of the macro instruction 
expands into a PTPB, all you need do is pass the address of the list 
form of the macro instruction to the execute form as the PARM value. 

The PUTLINE Parameter Block is defined by the IKJPTPB DSECT. Figure 
54 describes the contents of the PTPB. 


(, WAIT | /,NOHOLDW,NOBREAK \) 
[, NOWAIT/ \, HOLD f \, BREAKIN / 
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Number of 
Bytes 


Field 


Byte 

-. 0 . . 
.. 1 . . 
. *. 1 • 


Byte 

0 ... . 
• ..0 . 


Byte 2 


Contents or Meaning 


Control flags. These bits describe the 
output line to the PUTLINE Service Routine. 

The output line is a message. 

The output line is a data line. 

The output line is a single level or a single 
line. 

The output is multi-line. 

The output is multi-level. 

The output line is an informational message. 
Reserved bits. 

The format only function was requested. 
Reserved bits. 


TPUT options field. These bits indicate to 
the TPUT SVC which cf the TPUT options you 
want to use. 

Always set to 0 for TPUT. 

WAIT processing has been requested. Control 
will be returned to the issuer of PUTLINE 
only after the output line has been placed 
into a terminal output buffer. 

NOWAIT processing has been requested. 

Control will be returned to the issuer of 
PUTLINE whether or not a terminal output 
buffer is available. 

NOHOLD processing has been requested. The 
Command Processor that issued the PUTLINE can 
resume processing as soon as the output line 
has been placed on the output queue. 

HOLD processing has been requested. The 
Command Processor that issued the PUTLINE is 
not to resume processing until the output 
line has been written to the terminal or 
deleted. 

NOBREAK processing has been requested. The 
output line will be printed only when the 
terminal user is not entering a line. 

BREAKIN processing has been requested. The 
output line is to be sent to the terminal 
immediately. If the terminal user is 
entering a line, he is to be interrupted. 

EDIT processing has been requested. 

ASIS processing has been requested. 

CONTROL processing has been requested. 
Reserved. 

Reserved. 
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h~ 


Number of 
Bytes 


Field 


Contents or Meaning 


* 


PTPBOPUT 


PTPBFLN 


The address of the OUTPUT Line Descriptor 
(OLD) if the output line is a message. The 
address of the fullword header preceding the 
data if the output line is a single data 
line. The address of a forward-chain pointer 
preceding the fullword data header, if the 
output is multiline data. 




Address of the format only line. The PUTLINE 
service routine places the address of the 
formatted line into this field. 


Figure 54. The PUTLINE Parameter Block (Part 2 of 2) 


Types and Formats of Output Lines 

There are two types of output lines processed by the PUTLINE Service 
Routine s 

• Data Lines ( DATA) 

• Message lines (INFOR) 

The OUTPUT sublist operands you specify in the PUTLINE macro instruction 
indicate to the PUTLINE service routine which type of line you want 
processed (DATA, INFOR) f whether the output consists of one line, 
several lines, or several levels of messages (SINGLE, MULTLIN, MULTLVL,) 
and whether the line is to be written to the terminal (TERM), or 
formatted only (FORMAT). 

DATA LINES : A data line is the simplest type of output processed by the 
PUTLINE Service Routine. It is simply a line of text to be written to 
the terminal. PUTLINE does not format the line or process it in any 
way; it merely writes the line, as it appears, out to the terminal. 

There are two kinds of data lines, single line data and multiline data; 
each is handled differently by the PUTLINE service routine. 

Single Line Data : Single line data is one contiguous character string 
which PUTLINE places out to the terminal as one logical line. If the 
line of data you provide exceeds the terminal line length, the TPUT 
Routine segments the line and puts it out as several terminal lines. 
PUTLINE accepts single line data in the format shown in Figure 55. 
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Figure 55. PUTLINE Single Line Data Format 

You must precede your line of data with a 4-byte header field. The 
first two bytes contain the length of the output line, including the 
header; the second two bytes are reserved for offsets and are set to 
zero for data lines. You pass the address of the output line to the 
PUTLINE service routine by coding the beginning address of the four-byte 
header as the OUTPUT operand address in either the list or the execute 
form of the macro instruction. When the macro instruction expands, it 
places this data line address into the second word of the PUTLINE 
Parameter Block. 
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Figure 56 is an example of the code that could be used to write a 
single line of data to the terminal using the PUTLINE macro instruction. 
Note that the execute form of the PUTLINE macro instruction is used in 
this example to construct the Input Output Parameter List, and that the 
TERMPUT operands are not coded in either the list or the execute form of 
the macro instruction — the default values will be assumed by the 
PUTLINE service routine. 



Figure 56. Coding Example — PUTLINE Single Line Data 
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Multiline Data : Multiline data is a chain of single lines. Each line 
of data is processed by the PUTLINE service routine exactly as if it 
were single line data. Each element of the chain however, begins a new 
line to the terminal. By specifying multiline data (MULTLIN) in the 
PUTLINE macro instruction, you can put out several, variable length, 
non-contiguous lines at the terminal with one execution of the macro 
instruction. PUTLINE accepts Multiline data in a format similar to that 
of single line data except that each line is prefaced with a fullword 
forward chain pointer. Figure 57 shows the format of PUTLINE multiline 
data. 



Figure 57. PUTLINE Multi-Line Data Format 

Each of the forward chain pointers points to the next data line to be 
written to the terminal. The forward chain pointer in the last data 
line contains zeros. In the case of multiline data, you pass the 
address of the output line to the PUTLINE service routine by coding the 
beginning address of the first forward chain pointer as the OUTPUT 
operand address in either the list or the execute form of the macro 
instruction. When the macro instruction expands, it will place this 
multi-line data address into the second word of the PUTLINE Parameter 
Block. 
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Figure 58 is an example of the code required to write multiple lines 
of data to the terminal using the PUTLINE macro instruction. Note that 
the programmer has built his own IOPL rather than build it with the 
execute form of the PUTLINE macro instruction. Note also the use of the 
IKJIOPL and IKJCPPL DESECTS. These provide an easy method of accessing 
the fields within the IOPL and the CPPL f and they protect your code from 
changes made to the control blocks. 
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Figure 58. Coding Example -- PUTLINE Multi-Line Data (Part 1 of 2) 
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Figure 58. Coding Example — PUTLINE Multi-Line Data (Part 2 of 2) 


MESSAGE LINES : If you code INFOR in the PUTLINE macro instruction, the 
PUTLINE service routine writes the information you supply as an 
informational message and provides additional functions not applicable 
to data lines. An informational message is a line of output from the 
program in control to the user at the terminal. It Is used solely to 
pass output to the terminal; no input from the terminal is required 
after an informational message. 

There are two types of informational messages processed by the 
PUTLINE service routine: 

• Single Level Messages (SINGLE) 

• Multi-Level Message (MULTLVL) 


Single Level Messages : A single level message is composed of one or 
more message segments to be formatted and written to the terminal with 
one execution of the PUTLINE macro instruction. 

MultiLevel Messages : Multilevel messages are composed of one or more 
message segments to be formatted and written to the terminal, and one or 
more message segments to be formatted and placed on an internal chain in 
shared subpool 78. This internal chain can either be put out to the 
terminal or purged by a second execution of the PUTLINE macro 
instruction* 
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Passing the Message Lines to PUTLINE : You must build each of the 
message segments to be processed by the PUTLINE Service Routine as if it 
were a line of single line data. The segment must be preceded by a 
four-byte header field — the first two bytes containing the length of 
the segment, including the header, and the second two bytes containing 
zeros or an offset value if you use the text insertion facility. See 
"Using the PUTLINE Text Insertion Function" for a discussion of offset 
values. This message line format is required whether the message is a 
single level message or a multi-level message. 

Because of the additional operations performed on message lines 
however* you must provide the PUTLINE service routine with a description 
of the line or lines that are to be processed. This is done with an 
Output Line Descriptor (OLD). 

There are two types of Output Line Descriptors, depending on whether 
the messages are single level or multilevel. 

The OLD required for a single level message is a variable length 
control block which begins with a full word value representing the 
number of segments in the message, followed by full word pointers to 
each of the segments. 

The format of the OLD for multilevel messages varies from that 
required for single level messages in only one respect. You must 
preface the OLD with a full word forward chain pointer. This chain 
pointer points to another output line descriptor or contains zero to 
indicate that it is the last OLD on the chain. Figure 59 shows the 
format of the Output Line Descriptor. 
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|The address of the next OLD, or zero if this 
| is the last one on the chain. This field is 
j present only if the message pointed to is a 
|multi-level message. 

i 

i 

i_ 

4 

T 

1 

1 

_L_ 

none 

T 

(The number of message segments pointed to 
|this OLD. 

1 ... . . . ... ... 

by 

1- 

i 

L 

4 

T- 

1 

_J_ 

none 

t . ”” 

|The address of the first message segment. 

i 


r 

i 

i_ 

4 

T- 

1 

__1_ 

none 

“t ■ - - 

|The address of the next message segment. 

I ... ... .. .... ...... ... 


r 

1 4 

L 

Figure 59. 

+- 

[ 

The 

none 

Output 

T 

|The address of the nth message segment. 

- X 

Line Descriptor 

— 


You must build the Output Line Descriptor and pass its address to the 
PUTLINE Service Routine as the OUTPUT operand address in either the list 
or the execute form of the macro instruction. When the macro 
instruction expands, it places the address of the Output Line Descriptor 
into the second word of the PUTLINE Parameter Block. 

Figure 60 shows the two control block structures possible when 
processing a message line with PUTLINE. Note that the second word of 
the PUTLINE Parameter Block points to an Output Line Descriptor rather 
than directly to the message line itself. 
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PUTLINE Message Line Processing: 


In addition to writing a message out to the terminal, the PUTLINE 
service routine provides the following additional functions for message 
line (INFOR) processing: 

• Message Identification Stripping 

• Text Insertion 

• Formatting Only 

• Second level Informational Chaining 

Figure 61 shows the distribution of these PUTLINE Service Routine 
functions over the two output message types. 


FUNCTIONS 


j-- 

| Message I.D Stripping 


MESSAGE TYPES 

\r -t- 

Single Level | Multi-Level 


I— 

| Text Insertion 


h 

| Formatting Only 

h 


■H 


j Second Level Informational Chaining 

L-X. 


-J 


Figure 61. PUTLINE Functions and Message Types 


STRIPPING MESSAGE IDENTIFIERS : The user at the terminal indicates 
whether or not he wants message identifiers displayed at the terminal. 

He does this with the PROFILE command. (See the publications Command 
Language Reference and Terminal User's Guide .) If the terminal user has 
indicated that he does not want message identifiers displayed, the 
PUTLINE service routine strips them off the message before writing the 
message to the terminal. 

A message identifier must be a variable length character string, 
containing no leading or embedded blanks, must not exceed a maximum 
length of 255 characters, and must be terminated by a blank. 

Messages without message identifiers must begin with a blank. A 
message beginning with a blank is handled by the PUTLINE service routine 
as a message that does not require message identifier stripping, 
regardless of what the user at the terminal has requested. If you do 
not provide a message identifier, and do not begin your message with a 
blank, the beginning of your message up to the first blank, will be 
stripped off by the PUTLINE service routine if message identifier 
stripping is requested from the terminal. 


The following examples show the effects of the PUTLINE message 
identifier stripping function. 

If you provide message identifiers on your messages, and the terminal 
user does not request message I.D. stripping, your message will appear 
at the terminal exactly as it appears here: 


r-1 

j MESSAGEO010 THIS IS A MESSAGE. | 

L-J 
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If the user at the terminal requests message I.D. stripping, the 
message will appear as: 

i - 

| THIS IS A MESSAGE. 

L_ 

If you do not want to use message identifiers on your output 
messages, begin your message with a blank: 

r- 

| THIS IS A MESSAGE. 

L___ 

A message beginning with a blank is unaffected by a terminal user's 
request for message I.D. stripping, and will appear as you wrote it, 
minus the blank; that is: 

r-*- 1 

jTHIS IS A MESSAGE. | 

L__JJ 

USING THE PUTLINE TEXT INSERTION FUNCTION : The text insertion function 
of the PUTLINE service routine allows you to build or modify messages at 
the time you put them out to the terminal. With text insertion you can 
respond to different output message requirements with one basic message 
(the primary segment). You can insert text into this primary segment or 
add text to it, and thereby build an output message to meet the current 
processing situation. 

To use text insertion you pass your messages to the PUTLINE service 
routine as a variable number of text segments — from 1 to 255 segments 
are permissible. Each segment may contain from 0 to 255 characters, 
however, the total number of characters in all the segments must not 
exceed 256. You must precede each of these text segments with a four 
byte header — the first two bytes containing the length of the message, 
including the header, and the second two bytes containing an offset 
value. The offset value in the primary segment must be zero. The 
offset in any secondary segments may be from zero to the length of the 
primary segment's text field. An offset of zero in a secondary segment 
implies that the segment is to be placed before the primary segment. An 
offset that is equal to the length of the primary segment's text field 
implies that the secondary segment is to be placed after the primary 
segment. An offset of n, where n represents a value greater than zero 
but less than the total length of the primary segment, implies that the 
segment is to be inserted after the nth byte of the primary segment. 
PUTLINE places the secondary segment after that character, completes the 
message, and puts it out to the terminal. 

If you specify an offset in a secondary segment, greater than the 
length of the primary segment, PUTLINE cannot handle the request and 
returns a code of 12 (invalid parameters) in register 15. 


142 Guide to Writing a TMP or a CP (Release 21.6) 









If you provide more than one secondary segment to be inserted into a 
primary segment, the offset fields in each of the secondary segments 
must indicate the position within the original primary segment at which 
you want them to appear. PUTLINE determines the points of insertion by 
counting the characters of the original primary segment only. As an 
example, if you provided one primary and two secondary segments as 
shown: 


2 bytes 2 bytes 


28 bytes 


0| PLEASE ENTER TO PROCESSING | 
_X_J 


13[tEXT ] 

_X_J 


r 13] 

L-X- 


17]CONTINUE ] 

-X_I 


PUTLINE would place the first insert, TEXT, at the 14th character, and 
the second insert, CONTINUE, after the 17th character of the text field 
of the Primary segment. After PUTLINE inserts the two text segments, 
the message would read: 


jPLEASE ENTER TEXT TO CONTINUE PROCESSING! 


The leading and trailing blanks are automatically stripped off before 
the message is written to the terminal. 
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Figure 62 is an example of the code required to make use of the text 
insertion feature of the PUTLINE Service Routine; it uses the text 
segments shown above. 


Note that the operand INF0R f which indicates to the PUTLINE service 
routine that the text segments are to be processed as informational 
messages, requires an output line descriptor to point to the message 
segments. Only one Output Line Descriptor (ONEOLD) is required to point 
to the 3 messages segments because the 3 segments are to be combined 
into one single level message. 
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Figure 62. Coding Example — PUTLINE Text Insertion (Part 1 of 2) 
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Figure 62. Coding Example — PUTLINE Text Insertion (Part 2 of 2) 


USING THE FORMAT ONLY FUNCTION : You can also use the PUTLINE service 
routine to format a message but not write it at the terminal. To do 
this, code the FORMAT operand in the PUTLINE macro instruction and pass 
PUTLINE the same message segment structure required for the text 
insertion function. The PUTLINE service routine performs text insertion 
if requested and places the finished message in subpool 1 # which is not 
shared. It then places the address of the formatted line into the third 
word of the PUTLINE Parameter Block. The storage occupied by the 
formatted message belongs to your program and, if space is a 
consideration, must be freed by it. The returned formatted line is in 
the variable length record format; that is, it is preceded by a four 
byte header. You can use the first two bytes of this header to 
determine the length of the returned message, and later, to free the 
storage occupied by the message with the R form of the FREEMAIN macro 
instruction. 


One difference between format only processing and text insertion 
processing is that format only processing can be used only on single 
level messages. You cannot use the format only feature to format 
multilevel messages. You can however, use the second level 
informational chaining function of PUTLINE to format second level 
messages and place them on an internal chain. 
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BUILDING A SECOND LEVEL INFORMATIONAL CHAIN : PUTLINE can accept two 
levels of informational messages at each execution of the service 
routine. It formats the first level message and puts it out to the 
terminal. The second level message is formatted and a copy of it is 
placed on an internal chain in shared subpool 78. This internal chain, 
the second levei informational chain, is maintained by the I/O Service 
routines for the duration of one command or subcommand processor. You 
can use the PUTLINE service routine to purge this chain or to put it out 
to the terminal in its entirety. 

To purge the chain without putting it out to the terminal, you must 
turn on the high order bit in the first byte (ECTMSGF) of the third word 
of the Environment Control Table (ECT). The ECT is pointed to by the 
second word of the Input Output Parameter List, and may be mapped by the 
IKJECT DSECT• See Appendix A for a description of the ECT. The next 
time any chaining or unchaining is requested with PUTLINE or PUTGET, the 
second level informational chain will be eliminated. 

To put the entire chain out to the terminal, use the PUTLINE macro 
instruction and place a zero address where the output line address is 
normally required. This will cause the PUTLINE service routine to write 
the chain to the terminal and eliminate the internal chain. You will 
normally use this procedure only if your attention exit routine is using 
the PUTLINE macro instruction to process a question mark entered from 
the terminal. 

Figure 63 is an example of the code required to build a second level 
informational chain. It executes the PUTLINE service routine by using 
two different execute form macro instructions to modify the Putline 
Parameter Block built by the list form of the PUTLINE macro instruction. 

The code shown puts two messages out to the terminal and places two 
second level messages on an internal chain. It then executes a third 
execute form of the PUTLINE macro instruction with a zero OUTPUT= 
address to put the second level chain out to the terminal. 

Note that the offset value for the primary message segment must 
always be zero, and when placing second level messages on an internal 
chain, the offset value for the second level message must also be zero. 
Note also that you do not place a message identifier on a second level 
message. 
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Figure 63. Coding Example — PUTLINE Second Level Informational 
Chaining (Part 1 of 2) 
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Figure 63, Coding Example — PUTLINE Second Level Informational 
Chaining (Part 2 of 2) 
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Return Codes From PUTLINE 


When the PUTLINE service routine returns control to the program that 
invoked it, it provides one of the following return codes in general 
register fifteen: 

CODE MEANING 

decimal 

0 PUTLINE completed normally. 

4 The PUTLINE service routine did not complete. An attention 

interruption occurred during its execution, and the 
attention handler turned on the completion bit in the 
communications ECB. 

8 The NOWAIT option was specified and the line was not written 

to the terminal. 

12 Invalid parameters were supplied to the PUTLINE service 

routine. 

16 A conditional GETMAIN was issued by PUTLINE for output 

buffers and there was not sufficient space to satisfy the 
request. 


PUTGET - PUTTING A MESSAGE OUT TO THE TERMINAL AND OBTAINING A LINE OF 
INPUT IN RESPONSE 

Use the PUTGET macro instruction to put messages out to the terminal and 
to obtain a response to those messages. A message to the user at the 
terminal which requires a response is called a conversational message. 
There are two types of conversational messages: 

• Mode messages - Those which tell the user at the terminal which 
processing mode he is in so that he can enter a response applicable 
to that processing mode. Examples of mode messages are the READY 
sent to the terminal by the Terminal Monitor Program to indicate 
that it expects a Command to be entered, and the Command name (EDIT, 
TEST, etc.) sent by a Command Processor to indicate that it is 
ready to accept a subcommand name. 

• Prompt messages - Those which prompt the user at the terminal to 
enter parameters required by the program in control, or to reenter 
those parameters which were previously entered incorrectly. Prompt 
information can only be obtained from the user at the terminal. 

The input line returned by the PUTGET service routine can come from 
the terminal or from an in-storage list; PUTGET determines the source of 
input from the top element of the input stack unless you have specified 
the TERM or ATTN operands in the PUTGET macro instruction. 

PUTGET, like PUTLINE and GETLINE has many parameters. The parameters 
are passed to the PUTGET service routine according to the operands you 
code in the List and the Execute forms of the PUTGET macro instruction. 

This topic describes: 

• The list and execute forms of the PUTGET macro instruction. 

• Building the PUTGET Parameter Block. 

• Types and formats of the output line. 
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• Passing the message lines to PUTGET. 

• PUTGET processing, 

• Input line format - the input buffer, 

• An example of PUTGET. 

• Return codes from PUTGET. 

The PUTGET Macro Instruction - List Form 


The list form of the PUTGET macro instruction builds and initializes a 
PUTGET Parameter Block (PGPB) f according to the operands you specify in 
the PUTGET macro instruction. The PUTGET Parameter Block indicates to 

I the PUTGET service routine which of the PUTGET functions you want 
performed. Figure 64 shows the list form of the PUTGET macro 
instruction; each of the operands is explained following the figure. 
Appendix B describes the notation used to define macro instructions. 




,PROMPT 


OUTPUT= (output address (.SINGLE )I 

, MODE 

I) 

MULTLVL/ < 

,PTBYPS 



,TERM 

i 


[ ,ATTN 

IJ 


(EDIT ) 




{ASIS } 

(, WAIT \ 

L NOHOLD> 

/. NOBREAK U 

(control) 

|, NOWAIT / 

\, HOLD / 

(, BREAK IN | 


,TERMGET= (I EDIT M, WAIT ))1 ,MF=L 
\ASIS/ \,NOWAITJ 

L_i._X_H_ 

Figure 64. The List Form of the PUTGET Macro Instruction 


OUTPUT=output address 

Specify the address of the Output Line Descriptor or a zero. The 
Output Line Descriptor (OLD) describes the message to be put out, 
and contains the address of the beginning (the one-word header) of 
the message or messages to be written to the terminal. 

You have the option under MODE processing to provide or not provide 
an output message. If you do not provide an output line, code 
OUTPUT=0, and only the GET functions will take place. If you do 
provide an output message, the type of message and the processing 
to be performed by the PUTGET service routine are described by the 
OUTPUT sublist operands SINGLE, MULTLVL, PROMPT, MODE, PTBYPS, 

TERM, and ATTN. SINGLE and PROMPT are the default values . 


SINGLE 

The output message is a single level message. 


MULTLVL 

The output message consists of multiple levels. The first level 
message is written to the terminal, the secondary level messages 
are printed at the terminal, one at a time, in response to question 
marks entered from the terminal. Prompt must also be specified or 
defaulted to. 


PROMPT 

The output line is a prompt message. 
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MODE 


The output line is a mode message. 

PTBYPS 

The output line is a prompt message and the terminal user f s 
response will not print at those terminals that support the print 
inhibit feature. A terminal user can override bypass processing by 
hitting an attention followed by a carriage return before entering 
his input. 


TERM 

Specifies that the output line (a mode message) is to be written to 
the terminal,, and a line is to be returned from the terminal, 
regardless of the top element of the input stack. 

ATTN 

Specifies that the output line (a mode message) is to be initially 
suppressed but an input line is to be returned from the terminal. 


TERMPUT= 

Specifies the TPUT options requested. Since PUTGET issues a TPUT 
SVC to write the message to the terminal, this operand is used to 
indicate which of the TPUT options you want to use. The TPUT 
options are EDIT, ASIS or CONTROL, WAIT, or NOWAIT, NOHOLD, or 
HOLD,, and NOBREAK or BREAKIN. The default values are EDIT, WAIT, 
NOHOLD, and NOBREAK. 


EDIT 

Specifies that in addition to minimal editing (see ASIS), the 

following TPUT functions are requested: 

a. Any trailing blanks are removed before the line is written to 
the terminal. If a blank line is sent, the terminal vertically 
spaces one line. 

b. Control characters are added to the end of the output line to 
position the carrier to the beginning of the next line. 

c. All terminal control characters (for example: bypass, restore, 
horizontal tab, new line) are replaced with a printable 
character. "Backspace" is an exception; see (d.) under ASIS. 

ASIS 

Specifies that minimal editing is to be performed by TPUT as 

follows: 

a. The line of output is to be translated from EBCDIC to terminal 
code. Invalid characters will be converted to a printable 
character to prevent program caused I/O errors. This does not 
mean that all unprintable characters will be eliminated. 
"Restore", "upper case", "lower case", "bypass", and "bell 
ring", for example, might be valid but nonprinting characters 
at some terminals. (See CONTROL). 

b. Transmission control characters will be added. 

c. EBCDIC "NL", placed at the end of the message, indicates to the 
TPUT SVC that the carrier is to be returned at the end of the 
line. "NL" is replaced with whatever is necessary for that 
particular terminal type to cause the carrier to return. This 
"NL" processing occurs only if you specify ASIS, and the "NL" 
is the last character in your message. 

If you specify EDIT, "NL" is handled as described in (c.) 
under EDIT. 
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If the "NL" is embedded in your message, it is sent to the 
terminal as a carriage return. No idle characters are added 
(see f. below). This may cause overprinting, particularly on 
terminals that require a line-feed character to position the 
carrier on a new line. 

d. If you have used "backspace" in your output message, but the 
"backspace" character does not exist on the terminal type to 
which the message is being routed, TPUT attempts alternate 
methods to accomplish the backspace. 

e. Control characters are added as needed to cause the message to 
occur on several lines if the output line is longer than the 
terminal line size. 

f. Idle characters are sent at the end of each line to prevent 
typing as the carrier returns. 

CONTROL 

Specifies that the output line is composed of terminal control 

characters and will not print or move the carrier on the terminal. 

This option should be used for transmission of characters such as 

"bypass", "restore", or "bell ring". 


WAIT 

Specifies that control will not be returned to the program that 
issued the PUTGET until the output line has been placed into a 
terminal output buffer. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the PUTGET macro instruction, whether or not a terminal 
output buffer is available. If no buffer is available a return 
code of 18 (decimal) is returned. 

NOHOLD 

Specifies that control is to be returned to the issuer of the 
PUTGET macro instruction, and that program can resume processing as 
soon as the output line has been placed on the output queue. 


HOLD 

Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until this output line has been put 
out to the terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he 
is not to be interrupted. The output message is placed on the 
output queue to be printed after the terminal user has completed 
the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at 
the terminal is transmitting, he is interrupted, and this output 
line is sent. Any data that was received before the interruption 
is kept and displayed at the terminal following this output line. 

TERMGET= 

Specifies the TGET options requested. Since PUTGET issues a TGET 
SVC to bring in a line of data, this operand is used to indicate to 
the TGET SVC which of the TGET options you wish to use. The TGET 
options are EDIT or ASIS, and WAIT or NOWAIT. The default values 
are EDIT and WAIT. 
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EDIT 


Specifies that in addition to minimal editing (see ASIS), the 
buffer is to be filled out with trailing blanks. 

AS IS 

Specifies that minimal editing is to be done as follows: 

a. Transmission control characters are removed. 

b. The line of input is translated from terminal code to EBCDIC. 

c. Line deletion and character deletion editing is performed. 

d. Line feed and carriage return characters, if present, are 
removed. 

WAIT 

Specifies that control is to be returned to the program that issued 
the PUTGET macro instruction, only after an input message has been 
read. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the PUTGET macro instruction whether or not a line of input 
is available. If a line of input is not available, a return code 
of 20 (decimal) is returned in register 15 to the command 
processor. 

MF=L 

Indicates that this is the list form of the macro instruction. 


Note : In the list form of the PUTGET macro instruction, only 


r---1 

|PUTGET MF=L j 

L-J 


is required. 

The output line address is not specifically required in the list form of 
the PUTGET macro instruction, but must be coded in either the list or 
the execute form: 

r- 

|OUTPUT=(output addr ess) 

L_ 


Using the TSO I/O Service Routines for Terminal I/O 153 







The other operands and their sublists, as shown below, are optional 
because you can supply them in the execute form of the macro 
instruction, or if you want the default values, they are supplied 
automatically by the expansion of the macro instruction. 


OUTPUT=( 


f g SINGLE \ 

Lmultlvlj 


,PROMPT \ 
, MODE 
,PTBYPS 
, TERM 
, ATTN 


) 


(EDIT ) 




, TERMPUT= (l AS IS } 

/,WAIT ) 

f, NOHOLD | 

/, NOBREAK) 

(control) 

nowait; 

\,HOLD / 

\,breakin; 


,TERMGET= ( ( EDIT) /,WAIT )) 
lASISf 1.NOWAITf 


The operands you specify in the list form of the PUTGET macro 
instruction set up control information used by the PUTGET service 
routine. This control information is passed to the PUTGET service 
routine in the PUTGET Parameter Block, a four word parameter block built 
and initialized by the list form of the PUTGET macro instruction. 

The PUTGET Macro Instruction - Execute Form 

Use the execute form of the PUTGET macro instruction to prepare a mode 
or a prompt message for output to the terminal, to determine whether or 
not that message should be sent to the terminal, and to return a line of 
input, from.the source indicated by the top element of the input stack 
to the program that issued the PUTGET macro instruction. 

You can use the execute form of the PUTGET macro instruction to build 
and initiate the Input Output Parameter List required by the PUTGET 
service routine, and to request PUTGET functions not already requested 
by the list form of the macro instruction, or to change those functions 
previously requested in either a list form or a previous execute form of 
the PUTGET macro instruction. 

Figure 65 shows the execute form of the PUTGET macro instruction; 
each of the operands is explained following the figure. Appendix B 
describes the notation used to define macro instructions. 
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[symbol] 


PUTGET 


_JL_ 


[PARM=parameter address][,UPT=upt address] 
[,ECT=ect address][,ECB=ecb address] 



,PROMPT 


,OUTPUT=(output address(,SINGLE )| 

,MODE 

) 

MULTLVLJ < 

1 ,PTBYPS 



,TERM 



[ ,ATTN ] 



t 

it 


( EDIT ) -] 

,TERMPUT= (< AS IS > WAIT W, NOHOLD W. NOBREAK )) 
(CONTROL) (,NOWAIT / (,HOLD J \,BREAKIN/J 

TERMGET= ( / EDIT W, WAIT 


(ASIS NOWAIT 


}’] 


, ENTRY= /entry address]"! Jf MF= (E, / list address i) 


{ (15) 




\ ( 1 ) 




Figure 65. The Execute Form of the PUTGET Macro Instruction 


PARM=parameter address 

Specifies the address of the 4-word PUTGET Parameter Block (PGPB). 
This address is placed into the Input Output Parameter List (IOPL). 
It may be the address of a list form PUTGET macro instruction. The 
address is any address valid in an RX instruction, or you can put 
it in one of the general registers 2-12, and use that register 
number, enclosed in parentheses, as the PARM= address. 


UPT-upt address 

Specifies the address of the User Profile Table (UPT). This 
address is placed into the IOPL when the execute form of the PUTGET 
macro instruction expands. You can obtain this address from the 
Command Processor Parameter List (CPPL) pointed to by register one 
when the Command Processor is attached by the Terminal Monitor 
Program. The address can be used as received in the CPPL or you 
can put it in one of the general registers 2-12, and use that 
register number, enclosed in parentheses , as the UPT address. 

ECT=ect address 

Specifies the address of the Environment Control Table (ECT). This 
address is placed into the IOPL when the Execute form of the PUTGET 
macro instruction expands. You can obtain this address from the 
Command Processor Parameter List (CPPL) pointed to by register one 
when the Command Processor is attached by the Terminal Monitor 
Program. The address can be used as received in the CPPL or you 
can put it in one of the general registers 2-12, and use that 
register number, enclosed in parentheses, as the ECT address. 

ECB=ecb address 

Specifies the address of the Command Processor Event Control Block 
(ECB)• This address is placed into the IOPL by the execute form of 
the Putget macro instruction when it expands. 

You must provide a one-word Event Control Block and pass its 
address to the PUTGET service routine by placing the address into 
the IOPL. If you code the address of the ECB in the execute form 
of the PUTGET macro instruction, the macro instruction places the 
address into the IOPL for you. The address can be any address 
valid in an RX instruction, or you can put in one of the general 
registers 2-12, and use that register number, enclosed in 
parentheses, as the ECB address. 
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OUTPUT=output address 

Is the address of the Output Line Descriptor or a zero. The Output 
Line Descriptor (OLD) describes the message to be put out, and 
contains the address of the beginning (the one-word header) of the 
message or messages to be written to the terminal. 

You have the option under MODE processing to provide or not provide 
an output message. If you do not provide an output line, code 
OUTPUT=0, and only the GET functions will take place. If you do 
provide an output message, the type of message and the processing 
to be performed by the PUTGET Service Routine are described by the 
OUTPUT sublist operands SINGLE, MULTLVL, PROMPT, MODE, PTBYPS, 

TERM, and ATTN. The default values are SINGLE and PROMPT. 


SINGLE 

The output message is a single level message. 


MULTLVL 

The output message consists of multiple levels. The first level 
message is written to the terminal, the secondary level messages 
are printed at the terminal, one at a time, in response to question 
marks entered trom the terminal. PROMPT must also be specified or 
defaulted to. 


PROMPT 

The output line is a prompt message. 

MODE 

The output line is a mode message. 

PTBYPS 

The output line is a prompt message and the terminal user's 
response will not print at those terminals that support the print 
inhibit feature. A terminal user can override bypass processing by 
hitting an attention followed by a carriage return before entering 
his input. 

TERM 

Specifies that the output line (a mode message) is to be written to 
the terminal, and a line is to be returned from the terminal, 
regardless of the top element of the input stack. 

ATTN 

specifies that the output line (a mode message) is to be initially 
suppressed but an input line is to be returned from the terminal. 


TERMPUT= 

Specifies the TPUT options requested. PUTGET issues a TPUT SVC to 
write the message to the terminal, this operand is used to indicate 
which of the TPUT options you want to use. The TPUT options are 
EDIT, ASIS or CONTROL, WAIT or NOWAIT, NOHOLD or HOLD, and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD and NOBREAK. 


EDIT 

Specifies that in addition to minimal editing (see ASIS), the 

following TPUT functions are requested: 

a. Any trailing blanks are removed before the line is written to 
the terminal. If a blank line is sent, the terminal vertically 
spaces one line. 

b. Control characters are added to the end of the output line to 
position the carrier to the beginning of the next line. 

c. All terminal control characters (for example: bypass, restore, 
horizontal tab, new line) are replaced with a printable 
character. "Backspace" is an exception; see (d.) under ASIS. 
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AS IS 


Specifies that minimal editing is to be performed by TPUT as 
follows: 

a. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to 
prevent program caused I/O errors. This does not mean that all 
unprintable characters will be eliminated. "Restore", "upper 
case", "lower case", "bypass", and "bell ring", for example, 
might be valid but nonprinting characters at some terminals. 
(See CONTROL). 

b. Transmission control characters are added. 

c. EBCDIC "NL", placed at the end of the message, indicates to the 
TPUT SVC that the carrier is to be returned at the end of the 
line. "NL" is replaced with whatever is necessary for that 
particular terminal type to cause the carrier to return. This 
"NL" processing occurs only if you specify ASIS, and the "NL" 
is the last character in your message. 

If you specify EDIT, "NL" is handled as described in (c.) 
under EDIT. 

If the "NL" is embedded in your message, it is sent to the 
terminal as a carriage return. No idle characters are added 
(see f. below). This may cause overprinting, particularly on 
terminals that require a line-feed character to position the 
carrier on a new line. 

d. If you have used "backspace" in your output message, but the 
"backspace" character does not exist on the terminal type to 
which the message is being routed, TPUT attempts alternate 
methods to accomplish the backspace. 

e. Control characters are added as needed to cause the message to 
occur on several lines if the output line is longer than the 
terminal line size. 

f. Idle characters are sent at the end of each line to prevent 
typing as the carrier returns. 

CONTROL 

Specifies that this line is composed of terminal control characters 
and will not print or move the carrier on the terminal. This 
option should be used for transmission of characters such as 
"bypass", "restore", or "bell ring". 


WAIT 

Specifies that control will not be returned to the program that 
issued the PUTGET until the output line has been placed into 
terminal output buffer. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the PUTGET macro instruction, whether or not a terminal 
output buffer is available. If no buffer is available, a return 
code of 18 (decimal) is returned. 

NOHOLD 

Specifies that control is to be returned to the program that issued 
the PUTGET macro instruction, and it can continue processing as 
soon as the output line has been placed on the output queue. 
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HOLD 


Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until the output line has been put 
out to the terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he 
is not to be interrupted. The output message is placed on the 
output queue to be printed after the terminal user has completed 
the line. 

BREAKIN 

Specifies that output has precedence over input. If the user at 
the terminal is transmitting, he is interrupted, and this output 
line is sent. Any data that was received before the interruption 
is kept and displayed at the terminal following this output line. 

TERMGET= 

Specifies the TGET options requested. PUTGET issues a TGET SVC to 
bring in a line of data, this operand is used to indicate to the 
TGET SVC which of the TGET options you want to use. The TGET 
options are EDIT or ASIS, and WAIT or NOWAIT. The default values 
are EDIT and WAIT. 


EDIT 

Specifies that in addition to minimal editing (see ASIS), the 
buffer is filled out with trailing blanks. 

ASIS 

Specifies that minimal editing is done as follows: 

a. Transmission control characters are removed. 

b. The line of input is translated from terminal code to EBCDIC. 

c. Line deletion and character deletion editing is performed. 

d. Line feed and carriage return characters, if present, are 
removed. 

WAIT 

Specifies that control is to be returned to the program that issued 
the PUTGET macro instruction, only when an input message has been 
read. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the PUTGET macro instruction whether or not a line of input 
is available. If a line of input is not available, a return code 
of 20 (decimal) is returned in register 15. 

ENTRY= entry point address 
(15) 

Specifies the entry point of the PUTGET service routine. If ENTRY 
is omitted, the PUTGET macro expansion generates a LINK macro 
instruction to invoke the PUTGET service routine. The address may 
be any address valid in an RX instruction or (15) if you load the 
entry point address into general register 15. 


MF=E 

Indicates that this is the execute form of the PUTGET macro 
instruction. 
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listaddr 

( 1 ) 

The address of the 4-word Input Output Parameter List (IOPL). This 
can be a completed IOPL that you have built, or it may be 4 words 
of declared storage that will be filled from the PARM, UPT, ECT, 
and ECB operands of this execute form of the PUTGET macro 
instruction. The address must be any address valid in an RX 
instruction or (1) if you have loaded the parameter list address 
into general register 1. 

Note: In the execute form of the PUTGET macro instruction, only the 

following is required: 

f- 1 

|PUTGET MF=(E,flist address)) | 

I X (1) i I 

L_J 

The PARM=, UPT=, ECT=, and ECB= operands are not required if you have 
built your IOPL in your own code. 

The output line address is not specifically required in the execute form 
of the PUTGET macro instruction, but must be coded in either the list or 
the execute form: 

r- 1 

|OUTPUT=(output address) | 

L_ J 

The other operands and sublists are optional because you may have 
supplied them in the list form of the macro instruction or in a previous 
execute form; or because you may want to use the default values which 
are automatically supplied by the macro expansion itself. The other 
operands and sublists are: 


OUTPUT=( 


(, SINGLE ) 
UMULTLVL / 


) 


,PROMPT \ 
,MODE 
,PTBYPS 
,TERM 
, ATTN 


) 


( EDIT 

AS IS \ WAIT W, NOHOLD W, NOBREAK)) 
CONTROL) \, NOWAIT J \,HOLD |\,BREAKIN/ 

,TERMGET= ( (EDIT W,WAIT )) 

(AS IS J(, NOWAIT / 


The ENTRY= operand need not be coded in the macro instruction. If 
it is not, a LINK macro instruction is generated by the PUTGET macro 
expansion to invoke the PUTGET service routine. 

The operands you specify in the execute form of the PUTGET macro 
instruction set up control information used by the PUTGET service 
routine. You can use the PARM=, UPT=, ECT=, and ECB= operands of the 
PUTGET macro instruction to build, complete, or modify an IOPL. The 
OUTPUT=, TERMPUT=, and TERMGET= operands and their sublist operands 
initiate the PUTGET Parameter Block. The PUTGET Parameter Block is 
referenced by the PUTGET service routine to determine which functions 
you want PUTGET to perform. 
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Building the PUTGET Parameter Block (PGPB) 


When the list form of the PUTGET macro instruction expands, it builds a 
four-word PUTGET Parameter Block (PGPB). This PGPB combines the 
functions of the PUTLINE and the GETLINE parameter blocks and contains 
information used by the PUT and the GET functions of the PUTGET service 
routine. The list form of the PUTGET macro instruction initializes this 
PGPB according to the operands you have coded in the macro instruction. 
This initialized block, which you may later modify with the execute form 
of the PUTGET macro instruction, indicates to the PUTGET service routine 
the functions you want performed. It also contains a pointer to the 
Output Line Descriptor that describes the output message and it provides 
a field into which the PUTGET service routine places the address of the 
input line returned from the input source. 

You must pass the address of the PGPB to the execute form of the 
PUTGET macro instruction. Since the list form of the macro instruction 
expands into a PGPB, all you need do is pass the address of the list 
form of the macro instruction to the execute form as the PARM value. 

The PUTGET Parameter Block is defined by trie IKJPGPB DsECt. Figure 
66 describes the contents of the PUTGET parameter block. 


Figure 66. The PUTGET Parameter Block (Part 1 of 2) 


Number of 
Bytes 


Field 


Contents or Meaning 


Byte 

0 . , 

,1 . 


0 . 

.1 


xx.. . 
Byte 

1 ... , 
...1 . 
m m m m 

• xx. 


1 ... 

.XXX 


h~ 


PUT Control flags. These bits describe the 
output line to the PUTGET Service Routine. 

Always zero for PUTGET. 

The output line is a single level message. 
Must be zero for PUTGET. 

The output line is a multilevel message. 

The output line is a PROMPT message. 
Reserved. 

The output line is a MODE message. 

BYPASS processing is requested. 

ATTN processing is requested. 

Reserved. 


Byte 

0 ... . 
...0 . 


. ..1 


0 ... 


1 ... 


TPUT options field. These bits indicate to 
the TPUT SVC which of the TPUT options you 
want to use. 

Always set to 0 for TPUT. 

WAIT processing has been requested. Control 
will be returned to the issuer of TPUT only 
after the output line has been placed into a 
terminal output buffer. 

NOWAIT processing has been requested. 

Control will be returned to the issuer of 
TPUT whether or not a terminal output buffer 
is available. 

NOHOLD processing has been requested. The 
issuer of the TPUT can resume processing as 
soon as the output line has been placed on 
the output queue. 

HOLD processing has been requested. The 
issuer of the TPUT is not to resume 
processing until the output line has been 
written to the terminal or deleted. 
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Number of 
Bytes 


Field 


Contents or Meaning 


-H 


H- 


• . m « • 0 • • 

. 1 . . 


. 00 

.01 

..10 

•xx. .... 


Byte 2 


NOBREAK processing has been requested. The 
output line will be printed only when the 
terminal user is not entering a line. 
BREAKIN processing has been requested. The 
output line is to be sent to the terminal 
immediately. If the terminal user is 
entering a line, he is to be interrupted. 
EDIT processing has been requested. 

ASIS processing has been requested. 

CONTROL processing has been requested. 
Reserved 

Reserved. 

The address of the Output Line Descriptor. 


Byte 1 

.00 . 

••.1 .... 

X••. xxxx 

Byte 2 
xxxx xxxx 


GET control flags. 

Always zero for PUTGET. 

TERM processing is requested. 
Reserved bits. 


Reserved. 


-H 


Byte 1 
1 . 

...0 .... 




. 00 


..01 


.xx. xx.. 

Byte 2 
xxxx xxxx 


TGET options field. These bits indicate to 
the TGET SVC which of the TGET options you 
wish to use. 

Always set to 1 for TGET. 

WAIT processing has been requested. Control 
will be returned to the issuer of the TGET 
SVC only after an input message has been 
read. 

NOWAIT processing has been requested. 

Control will be returned to the issuer of the 
TGET SVC whether or not a line of input is 
available. If no line was available, PUTGET 
returns a code of 20 (decimal) in general 
register 15. 

EDIT processing has been requested. In 
addition to the editing provided by ASIS 
processing , the input buffer is to be filled 
out with trailing blanks to the next 
doubleword boundary. 

ASIS processing has been requested. (See the 
ASIS operand of the PUTGET macro instruction 
description). 

Reserved bits. 


Reserved. 


-H 


PGPBIBUF 


The address of the input buffer. The PUTGET 
Service Routine fills this field with the 
address of the input buffer in which the 
input line has been placed. 


L_X_X_ 

Figure 66. The PUTGET Parameter Block (Part 2 of 2) 
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Types and Formats of the Output Line 


The PUTGET Service Routine writes only conversational messages to the 
terminal; it does not handle data lines. For information on how to 
write a data line or a nonconversational message to the terminal, see 
the section on the PUTLINE macro instruction. 

PUTGET accepts two output line formats depending upon whether the 
message you provide is a single level message or a multilevel message. 

SINGLE LEVEL MESSAGES : A single level message is composed of one or 
more message segments to be formatted and written to the terminal with 
one execution of the PUTGET macro instruction. 

MULTI-LEVEL MESSAGES : Multilevel messages are composed of one or more 
message segments to be formatted and written to the terminal, and one 
or more message segments to be formatted and printed to the terminal in 
response to question marks entered from the terminal. Note however, 
that if you specify MODE in the PUTGET macro instruction, you can 
process only single level messages. If you specify PROMPT in the 
PUTGET macro instruction, then these second level messages will be 
written to the terminal, one at a time, in response to successive 
question marks entered from the terminal. If these PROMPT messages are 
to be available to the user at the terminal however, the top element of 
the input stack must not specify a procedure element as the current 
source of input, and the terminal user must not have inhibited 
prompting. (See the PROFILE command in the TSO Command Language 
Reference. 


Passing the Message Lines to PUTGET 

You must build each of the message segments to be processed by the 
PUTGET service routine as if it were a line of single line data. The 
segment must be preceded by a four-byte header field — the first two 
bytes containing the length of the segment including the header, and 
the second two bytes containing zeros or an offset value if you use the 
text insertion facility provided by PUTGET. This message line format 
is required whether the message is a single level message or a 
multilevel message. 

Because of the additional functions performed on message lines — 
message ID stripping, text insertion, and multi-level processing — you 
must provide the PUTGET Service Routine with a description of the line 
or lines that are to be processed. This is done with an OUTPUT Line 
Descriptor (OLD). 

There are two types of Output Line Descriptors depending on whether 
the messages are single level or multilevel. 

The OLD required for a single level message is a variable length 
control block which begins with a fullword value representing the 
number of segments in the message, followed by fullword pointers to 
each of the segments. 

The format of the OLD for multilevel messages varies from that 
required for single level messages in only one respect. You must 
preface the OLD with a fullword forward chain pointer. This chain 
pointer points to another Output Line descriptor or contains zero to 
indicate that it is the last OLD on the chain. Figure 67 shows the 
format of the Output Line Descriptor. 


162 Guide to Writing a TMP or a CP (Release 21.6) 




Number of 
Bytes 


Field 



r- i 

I I 

| Contents or Meaning | 

-+-* 


|The address of the next OLD, or zero if this 


j is the last one on the chain. This field is | 

j present only if the message pointed to is a j 
|multi-level message. | 

+- 1 

|The number of message segments pointed to by | 

|this OLD. | 

+-1 

| The address of the first message segment. | 

+-1 

|The address of the next message segment. | 

+-f 

|The address of the nth message segment. | 

.j_ j 


Figure 67. The Output Line Descriptor (OLD) 


You must build the Output Line Descriptor and pass its address to the 
PUTLINE service routine as the OUTPUT operand address in either the list 
or the execute form of the macro instruction. When the macro 
instruction expands, it places this OLD address into the second word of 
the PUTLINE Parameter Block. 


Figure 68 shows the two control block structures possible when 
passing an output message to the PUTGET service routine. Note that 
MODE, TERM, or ATTN may not be coded in the PUTGET macro instruction if 
you want to provide multilevel messages to the terminal. (Mode messages 
can have only one level.) 
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PUTGET Processing 


Text insertion and message identifier stripping are available to all 
output messages processed by the PUTGET service routine. For a detailed 
description of these functions see the section headed "PUTLINE Message 
Line Processing." 

The PUTGET service routine provides other processing capabilities 
dependent upon whether the message is a MODE or a PROMPT message. 

MODE MESSAGE PROCESSING : A MODE message is a message put out to the 
terminal when a command or a subcommand is anticipated. The processing 
of MODE messages by the PUTGET service routine is dependent upon the 
following two conditions: 

1. Are you providing an output line? 

2. From what source is the input line coming? 

Is an Output Line Present : You need not provide an output line to the 
PUTGET service routine. If you do provide an output line address then 
PUT processing will take place. Whether your output line is written to 
the terminal is then dependent upon the input source indicated by the 
input stack. If you do not provide an output line (OUTPUT=0) then only 
the GET function of the PUTGET service routine takes place. 

What is the Input Source : The source of the input line, as determined 
by the top element of the input stack, determines the type of processing 
performed by the PUTGET service routine. You may however override the 
input stack by coding the TERM or ATTN operands in the PUTGET macro 
instruction. The two sources of input supported are: 

1. Terminal 

2. In-storage 

If the current source of input is the terminal, and you provide an 
output line, the PUTGET service routine writes the line to the terminal, 
returns a line from the terminal, and places the address of the returned 
line into the fourth word of the PUTGET Parameter Block. If the line 
returned from the terminal is a question mark however, the PUTGET 
service routine causes the secondary level informational message chain 
(if one exists) to be written to the terminal, again puts out the mode 
message, and then returns a line from the terminal. If the user at the 
terminal enters a question mark in response to a mode message, and no 
second level message chain exists, PUTGET puts out the message 
"IKJ66760I NO INFORMATION AVAILABLE", puts the mode message out again, 
and returns a line from the terminal. 

Note that if the user enters a question mark from the terminal, the 
second level chain returned to the terminal is not related to the 
current mode message but to the Command Processor just terminated; mode 
messages can have only one level. 

If the current source of input is an in-storage list, the output line 
(if you provide one) is ignored and the PUTGET Service Routine normally 
obtains an input line from the in-storage list and places a pointer to 
that line in the fourth word of the PGPB. If however, a second level 
information chain exists, PUTGET will only return a line if the user at 
the terminal has access to the information in the chain through the 
PAUSE mechanism. If the chain is not available to the user, no line is 
obtained by PUTGET, and it returns a code of 12 in register 15. You can 
test this return code, and if you want, recover from this error 
condition by turning on the high order bit of the ECTMSGF field of the 
Environment Control Table (see Appendix A) and reissuing the PUTGET. 

The second level information chain is then purged and a line is obtained 
from the in-storage list. 


Using the TSO I/O Service Routines for Terminal I/O 165 



PAUSE PROCESSING : If the user at the terminal has requested the PAUSE 
option on the PROFILE command, the PUTGET Service Routine makes the 
chained second level informational messages available to him, even if 
the current input source is not the terminal. 

PAUSE processing works as follows. If a second level informational 
chain does exist, PUTGET puts out the message 'IKJ56762A PAUSE' to the 
terminal informing the terminal user that PAUSE processing is in effect. 
At this point the terminal user can enter either a question mark to 
indicate that he wishes to have the chained second level messages put 
out to the terminal, or a carriage return to indicate that the 
information is not needed. If the user enters a carriage return, the 
second level informational message chain is eliminated. If he enters 
any response other than a question mark or a carriage return, PUTGET 
prompts him for a correct response. 

PROMPT MESSAGE PROCESSING : A PROMPT message is a message put out to the 
terminal when the program in control requires input from the terminal 
user. PROMPT information must come from the terminal and can not be 
obtained from any other source of input. There are two cases when a 
request for PROMPT processing is denied by PUTGET: 

1. When the current source of input, as determined by the top element 
of the input stack, is an in-storage procedure. 

2. When the terminal user has requested via the PROFILE command that 
no prompting be done. 

If PROMPT processing is allowed, the PUTGET service routine writes the 
first level message to the terminal and obtains an input line from the 
terminal. If the input line is a question mark, PUTGET either returns 
the next level message provided, or a message informing the user that no 
information is available. PUTGET continues to respond to question marks 
entered from the terminal by writing one more secondary level message to 
the terminal in response to each question mark entered until the chain 
is exhausted; at that point PUTGET issues a message informing the user 
at the terminal that no more information is available. The prompt 
message is not repeated and the task goes into an input wait until the 
terminal user enters a line. When a line is obtained from the terminal, 
PUTGET places the address of the line into the fourth word of the PGPB. 

Input Line Format - the Input Buffer 

The fourth word of the PUTGET Parameter Block contains zeros until the 
PUTGET service routine returns a line of input. The service routine 
places the requested input line into an input buffer beginning on a 
doubleword boundary located in subpool 1. It then places the address of 
this input buffer into the fourth word of the PGPB. The input buffer 
belongs to the program that issued the PUTGET macro instruction. The 
buffer or buffers returned by PUTGET are automatically freed when your 
code relinquishes control. If space is limited, you should free the 
input buffer with the FREEMAIN macro instruction after you have 
processed or copied the input line. 
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Regardless of the source of input, an in-storage list or the 
terminal, the input line returned by the PUTGET service routine is in a 
standard format. All input lines are in the variable length record 
format with a fullword header followed by the text returned by PUTGET. 
Figure 69 shows the format of the input buffer returned by the PUTGET 
Service Routine. 



Figure 69. Format of the PUTGET Input Buffer 

The two-byte length field contains the length of the returned input 
line including the header (4 bytes). You can use this length field to 
determine the length of the input line to be processed, and later, to 
free the input buffer with the R form of the FREEMAIN macro instruction. 
The two-byte offset field is always set to zero on return from the 
PUTGET Service Routine. 
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Figure 70 shows the PUTGET control block structure for a multilevel 
PROMPT message after the PUTGET service routine has returned an input 
line. 



Figure 70. PUTGET Control Block Structure - Input Line Returned 


An Example of PUTGET 

Figure 71 is an example of the code required to execute the PUTGET macro 
instruction. The code uses a multilevel PROMPT message as the PUTGET 
output line. It assumes that a line of input will be returned from the 
terminal and tests only for a zero return code (PUTGET completed 
normally). 
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The execute form of the PUTGET macro instruction builds the I/O 
parameter list, using the addresses of the user profile table and the 
environment control table supplied in the Command Processor Parameter 
List. In addition, the I/O parameter list contains the address of an 
ECB built by the code, and the address of the list form of the PUTGET 
macro instruction as the PUTGET Parameter Block address. 


Note that the TERMPUT, TERMGET, and ENTRY operands are not coded; the 
default values are used. Note also that this code is effective only if 
the top element of the input stack indicates a non-procedure as the 
current source of input. 
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Figure 71. Coding Example — PUTGET Multi-Level PROMPT Message (Part 1 
of 3) 
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Figure 71. Coding Example — PUTGET Multi-Level PROMPT Message (Part 2 
of 3) 
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Figure 71. Coding Example -- PUTGET Multi-Level PROMPT Message (Part 3 
of 3) 
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Return Codes From PUTGET 


When the PUTGET Service Routine returns control to the program that 
invoked it f it provides one of the following return codes in general 
register 15. 

CODE MEANING 

decimal 

0 PUTGET completed normally. 

The line obtained came from the terminal. 

4 PUTGET completed normally. 

The line obtained did not come from the terminal. (MODE 
messages only) 

8 The PUTGET service routine did not complete. An attention 

interrupt occurred during the execution of PUTGET, and the 
attention handler turned on the completion bit in the 
communications ECB. 

12 No prompting was allowed on a PROMPT request. Either the 

user at the terminal requested no prompting with the PROFILE 
command, or the current source of input is an in-storage 
list. 

12 A line could not be obtained after a MODE request. A chain 

of second level informational messages exists, and the 
current stack element is non-terminal, but the terminal user 
did not request PAUSE processing with the PROFILE command. 
The messages are therefore not available to him. 

16 The NOWAIT option was specified for TPUT and no line was put 

out or received. 

20 The NOWAIT option was specified for TGET and no line was 

received. 

24 Invalid parameters were supplied to the PUTGET service 

routine. 

28 A conditional GETMAIN was issued by PUTGET for output 

buffers and there was not sufficient space to satisfy the 
request. 
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Using the TGET/TPUT SVC for Terminal I/O 


A supervisor call routine, SVC 93, reached through the TGET and TPUT 
macro instructions, provides a route for program I/O to a terminal. The 
Basic Sequential Access Method, the Queued Sequential Access Method, and 
the TSO I/O Service Routines all use SVC93 to process terminal I/O. You 
can use this method in any TSO routines you write, and in any 
applications programs that run under TSO control. If you do use 
TGET/TPUT in an applications program however, that program becomes TSO 
dependent. The TGET and TPUT macro instructions become NOPs in a batch 
environment. 


The TGET and TPUT macro instructions do not require that you build 
control blocks for their use. The operands you code into each of these 
macro instructions specify the location and size of the TGET or TPUT 
buffers, and the SVC functions you want performed. The functions 
provided by the TGET/TPUT SVC are not as extensive, however, as those 
provided by the Terminal I/O service routines. 

Both the TGET and the TPUT macro instructions have a standard form 
and a register form. 

This section discusses: 

• The TPUT Macro Instruction 

• The TGET Macro Instruction 

• Formatting the TGET/TPUT Parameter Registers 

• Examples of TGET and TPUT 
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The TPUT Macro Instruction - Writing a Line to the Terminal 


Use the TPUT macro instruction (SVC 93) to transmit a line of output to 
the terminal. You can use the TPUT macro instruction in any TSO 
routines you write, and in any applications programs to be run under 
TSO. Note however, that TPUT does not provide message ID stripping, 
text insertion, or second level message chaining. If you require these 
features, use the PUTLINE macro instruction. 

Figure 72 shows the format of the TPUT macro instruction; the figure 
combines the standard and the register form. Each of the operands is 
explained following the figure. Appendix B describes the notation used 
to define macro instructions. 


[symbol] |TPUT (buffer address,buffer size 


|“, EDIT 

l:’" 


io 

CONTROL 


lr 

JL: 


, WAIT 

NOWAIT 


r ir -\ 

I ,NORUED | | .NOBREAK I 

L, HOLD 

J L.BREAKINJ 

f“,HIGHP“ 

1 r,TJID=id ] 

Llowp 

I I,TJIDLOC=address| 


,R 

L-J.--_T_J 

Figure 72. The TPUT Macro Instruction — Standard and Register Forms 


buffer address 

Standard form : The address of the buffer that holds your line of 
output. This can be any address acceptable in an RX instruction, 
or the address can be placed in one of the general registers 1-12, 
and that register specified within parenthesis. 

Register form : The register which contains the parameters to be 
passed in register 1 to the TPUT SVC. When the R format is 
specified, this operand must be in one of the general registers 
1-12, and that register specified within parentheses. See the 
section headed 'Formatting the TGET/TPUT Parameter Registers' for a 
discussion of the register contents. 

buffer size 

Standard form : The size of the output buffer in bytes. The 
allowable range is from 0 through 32,767 bytes. You can specify 
this buffer size directly as a number, or you can place the buffer 
size into one of the general registers 0, or 2-12, and specify that 
register within parentheses. 

Register form : The register which contains the parameters to be 
passed in register 0 to the TPUT SVC. When the R format is 
specified this operand must be in one of the general registers 0, 
or 2-12, and that register specified within parentheses. See the 
section "Formatting the TGET/TPUT Parameter Registers" for a 
discussion of the register contents. 


Indicates that this is the register form of the TPUT macro 
instruction. You must place the parameters you want passed to the 
TPUT SVC into two registers and specify those registers as the 
first two operands of the macro instruction. The parameters must 
be arranged in the registers in the format shown in the section 
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headed B Formatting the TGET/TPUT Parameter Registers 1 . The R 
operand and all other optional operands are mutually exclusive. 

If both R and any other optional operands are coded, the macro will 
not expand. 


EDIT 

Indicates that in addition to minimal editing (see ASIS) the 

following TPUT functions are requested: 

a. All trailing blanks are removed before the line is written to 
the terminal. If a blank line is sent, the terminal vertically 
spaces one line. 

b. Control characters are added to the end of the output line to 
position the carrier to the beginning of the next line. 

c. All terminal control characters (for example: bypass, restore, 
horizontal tab, new line) are replaced with a printable 
character. "Backspace" is an exception; see (d.) under ASIS. 

EDIT is the default value among the EDIT, ASIS, and CONTROL 

operands. 

ASIS 

Indicates that minimal editing is to be performed by the TPUT SVC 

as follows: 

a. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to 
prevent program caused I/O errors. This does not mean that all 
unprintable characters will be eliminated. "Restore", f upper 
case", "lower case", "bypass", and "bell ring", for example, 
might be valid but nonprinting characters at some terminals. 
(See CONTROL). 

b. Transmission control characters are added. 

c. EBCDIC "NL", placed at the end of the message, indicates to the 
TPUT SVC that the carrier is to be returned at the end of the 
line. "NL" is replaced with whatever is necessary for that 
particular terminal type to cause the carrier to return. This 
"NL" processing occurs only if you specify ASIS, and the "NL" 
is the last character in your message. 

If you specify EDIT, "NL" is handled as described in (c.) 
under EDIT. 

If the "NL" is embedded in your message, a semicolon is 
substituted for "NL" and sent to the terminal. No idle 
characters are added (see f. below). This may cause 
overprinting, particularly on terminals that require a 
line-feed character to position the carrier on a new line. 

d. If you have used "backspace" in your output message, but the 
"backspace" character does not exist on the terminal type to 
which the message is being routed, the "backspace" character is 
removed from the output message. 

e. Control characters are added as needed to cause the message to 
print on several lines if the output line is longer than the 
terminal line size. 
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f. A sufficient number of idle characters is added to the end of 
each output line to prevent the transmission of output to the 
terminal while the carrier is being returned to the left-hand 
margin. 

CONTROL 

Indicates that this line is composed of terminal control characters 
and will not print or move the carrier on the terminal. This 
option should be used for transmission of characters such as 
"bypass", "restore", or "bell ring". 


WAIT 

Specifies that control will not be returned to the program that 
issued the TPUT macro instruction until the output line has been 
placed into a terminal output buffer. If no buffers are available, 
the issuing program will be placed into a wait state until buffers 
become available, and the output line is placed into them. 

WAIT is the default value for the WAIT and NOWAIT operands. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the TPUT macro instruction, whether or not a terminal output 
buffer is available for the output line. If no buffer is 
available, the TPUT SVC returns a code of 04 (hex) in register 15. 

NOHOLD 

Indicates that control is to be returned to the program that issued 
the TPUT macro instruction as soon as the output line has been 
placed in terminal output buffers. 

NOHOLD is the default value for the NOHOLD and HOLD operands. 


HOLD 

Specifies that the program that issued the TPUT macro instruction 
cannot continue its processing until this output line has been 
written to the terminal or deleted. 

NOBREAK 

Specifies that if the terminal user has started to enter input, he 
is not to be interrupted. The output message is placed on the 
output queue to be printed after the terminal user has completed 
the line. 

NOBREAK is the default value for the NOBREAK and BREAKIN operands. 
BREAKIN 

Specifies that output has precedence over input. If the user at 
the terminal has started to enter input, he is interrupted, and 
this output line is sent. Any data that was received before the 
interruption is kept and displayed at the terminal following this 
output line. 


HIGHP 

Specifies that this message must be sent to the terminal, even 
though the destination terminal has disallowed messages from other 
terminals. This operand counters the effect of the interterminal 
communication bit when set in the terminal status block* (TSB)• 
(The HIGHP operand is used by the OPERATOR SEND subcommand and the 
SEND operator command.) The operand is recognized only if the 
issuing task is operating under zero protection key. The TJID 
keyword must also be specified. HIGHP is the default if neither 
HIGHP nor LOWP is specified, and the issuing program is operating 
under zero protection key. 


*See the TSO Control Program, Program Logic Manual for a description of 
the terminal status block (TSB). 
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LOWP 


Specifies that the TPUT with TJID module should test the 
interterminal communication bit in the terminal status block. If 
the user of the destination terminal allows interterminal messages, 
this message will be sent,. If such messages are not allowed the 
message will not be sent, and the return code of , 0C* will indicate 
no message was sent. The LOWP operand is recognized only when TJID 
is specified. The issuer must be operating under zero protection 
key. 

If LOWP is specified, the issuing program should have an alternate 
method of transmitting the message to the terminal user. For 
example, a message data set could be used. 

TJID or TJIDLOC 

Specifies the TJID (terminal job identifier) of the target 
terminal, or the address of that TJID. This facility is used for 
supervisor communication with the terminal, and for inter-user 
conversation between terminals (the SEND command). If this option 
is used, NOHOLD is the required option and is defaulted to. If you 
specify TJID, you must supply a TJID number, or the number of a 
register containing the TJID number. The register number must be 
enclosed within parentheses. If TJIDLOC is used, you must supply 
the address of a halfword containing the TJID. 

TJID or TJIDLOC can be specified in registers 2-12, right adjusted. 
The TJID is located in the 2 byte TJBTJID field of the Terminal Job 
Block associated by USERID (the TJBUSER field) with the user you 
wish to send to. See Appendix A for a description of the Terminal 
Job Block. 

Note : If a TPUT without TJID is coded in a background program, the 

result is a NOP. If however, the TPUT specifies TJID, the message is 

sent to the target terminal. 


RETURN CODES FROM TPUT 

When it returns control to the program that invoked it, the TPUT SVC 
supplies one of the following return codes in general register 15. 

Code (hexadecimal) Meaning 

00 TPUT completed successfully. 

04 NOWAIT was specified and no terminal output buffer 

was available. 

08 An attention interruption occurred while the TPUT 

SVC routine was processing. 

0C A TPUT macro instruction with a TJID operand was 

issued but the user at the terminal indicated by 
the TJID requested that inter-terminal messages 
not be printed on his terminal. The message was 
not sent. 

10 Invalid parameters were passed to the TPUT SVC. 

14 The terminal has been disconnected and could not 

be reached. 
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The TGET Macro Instruction -- Getting a Line From the Terminal 


Use the TGET macro instruction to read a line of input from the 
terminal. A line of input is defined as all the data between the 
beginning of the input line and a line-end delimiter. A line-end 
delimiter is any character or combination of characters which causes the 
carrier to return to the left-hand margin on a new line, or which 
terminates transmission from the terminal. 

You can use the TGET macro instruction in any TSO routines, and in 
any applications programs to be run under TSO. Note however, that TGET 
does not provide access to in-storage lists, nor does it perform any 
type of logical line processing on the returned line. If you require 
these features, use the GETLINE macro instruction. 

Each time TGET returns control to your program, register 1 contains 
the number of bytes of data actually moved from the terminal to your 
input buffer. If your buffer is smaller than the line of input entered 
at the terminal, only as much of the input line as can be contained in 
the input buffer is moved. Return code OC indicates that only part of 
the line was obtained by TGET. You must then issue as many TGET macro 
instruction as are required to get the rest of the line of input. 

Figure 73 shows the format of the TGET macro instruction; it combines 
the standard and the register form. Each of the operands is explained 
following the figure. Appendix B describes the notation used to define 
macro instructions. 
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Figure 73. The TGET Macro Instruction — Standard and Register Forms 
buffer address 

Standard form : The address of the buffer that is to receive the 
input line. This can be any address acceptable in an RX 
instruction, or the address can be placed in one of the general 
registers 1-12, and that register specified within parentheses. 

Register form : The register which contains the parameters to be 
passed in register 1 to the TGET SVC. When the R format is 
specified, this operand must be in one of the general registers 
1-12, and that register specified within parentheses. See the 
section headed 'Formatting the TGET/TPUT Parameter Registers' for a 
discussion of the register contents. 

buffer size 

Standard form : The size of the input buffer in bytes. The 
allowable range is from 0 through 32,767 bytes. You can specify 
this buffer size directly as a number, or you can place the buffer 
size into one of the general registers 0, or 2-12, and specify that 
register within parentheses. 

Register form : The register which contains the parameters to be 
passed in register 0 to the TGET SVC. When the R format is 
specified this operand must be in one of the general registers 0, 
or 2-12, and that register specified within parentheses. See the 
topic 'Formatting the TGET/TPUT Parameter Registers' for a 
discussion of the register contents. 
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Indicates that this is the register form of the TGET macro 
instruction. You must place the parameters you want passed to the 
TGET SVC into two registers and specify those registers as the 
first two operands of the macro instruction. The parameters must 
be arranged in the registers in the format shown in the section 
headed •Formatting the TGET/TPUT Parameter Registers*. 

The R operand and all other optional operands are mutually 
exclusive. 

If both R and any other optional operands are coded, the macro will 
not expand. 


EDIT 

Specifies that in addition to minimal editing (see ASIS), the 

following TGET functions are requested: 

a. All terminal control characters (that is, nongraphic characters 
such as bypass, line feed, restore, prefix and the character 
immediately following it, etc.) are removed from the data. 

b. The horizontal tab (HT) character and the backspace (BS) 
character, when backspace is not used for character deletion, 
remain in the data. 

c. The buffer is filled out with blanks, if the returned input 
line is shorter than the input buffer length. These blanks are 
not included in the character count returned in register 1. 

EDIT is the default value for the EDIT and ASIS operands. 


ASIS 

Specifies that minimal editing is done as described below: 

a. Transmission control characters are removed. 

b. The returned input line is translated from terminal code to 
EBCDIC. Invalid characters are compressed out of the data. 

c. Line deletion and character deletion are performed according to 
the specifications in the Terminal Status Block. 

d. New line (NL), carriage return (CR), and line feed (LF) 
characters, if present at the end of the line, are not included 
in the data count returned in register one. 

e. After the input message has been received, the carrier is 
returned to the left-hand margin of the next line before any 
output to the terminal is allowed. 

WAIT 

Specifies that control will not be returned to the program that 
issued the TGET macro instruction until the input line has been 
placed into your input buffer. If an input line is not available 
from the terminal, the issuing program is placed into a wait state 
until a line becomes available and is read into your input buffer. 
WAIT is the default value for the WAIT and NOWAIT operands. 

NOWAIT 

Specifies that control should be returned to the program that 
issued the TGET macro instruction, whether or not an input line is 
available from the terminal. If no line is returned, the TGET SVC 
returns a code of 04 (hex) in register 15. 
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RETURN CODES FROM TGET 


When it returns control to the program that invoked it, the TGET SVC 
supplies the length of the message moved into your buffer in register l f 
and one of the following return codes in general register 15. 

Code (hexadecimal) Meaning 

00 TGET completed successfully. Register 1 contains 

the length of the input line read into your input 
buffer. 

04 NOWAIT was specified and no input was available to 

be read into your input buffer. 

08 An attention interruption occurred while the TGET 

SVC routine was processing. 

0C Your input buffer was not large enough to accept 

the entire line of input entered at the terminal. 
Subsequent TGET macro instructions will obtain the 
rest of the input line. 

10 Invalid parameters were passed to the TGET SVC. 

14 The terminal has been disconnected and could not 

be reached. 
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Formatting the TGET/TPUT Parameter Registers 


If you use the Register format of the TGET or TPUT macro instruction, 
you must code the parameters you want passed to the TGET/TPUT SVC into 
two registers. You specify these two registers enclosed in parentheses 
as the first two operands of the TGET or TPUT macro instruction, 
followed by the R operand to indicate that you are executing the 
register form of the macro instruction. 

If the registers you specify as the first and second operand of the 
macro instruction are register 1 and register 0 respectively, the TGET 
or TPUT macro instruction expands directly to the TGET/TPUT SVC. If you 
specify other permissible registers, registers 2-12, the macro expands 
to load registers one and zero from the registers you specify before 
issuing the SVC. 

The registers must be formatted as shown in Figure 74. 


RO 


R1 


Terminal Job 

1. D. (TJID) 

Buffe 

r Size 

* 


Flags 

Address of your Input or Output Buffer 


Figure 74. TGET/TPUT Parameter Registers 


* Flags 
One Byte 


0 ... 
1 ... 


xx. 


0 

1 


0 ... 
1 ... 
. 0 .. 
. 1 .. 
..00 


..01 


. .10 


Always set to 0 for TPUT. 

Always set to 1 for TGET. 
Reserved bits. 

WAIT processing is requested. 
NOWAIT processing is requested. 
NOHOLD processing is requested. 
HOLD processing is requested. 
NOBREAK processing is requested. 
BREAK processing is requested. 
EDIT processing is requested. 

ASIS processing is requested. 
CONTROL processing is requested. 
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Coding Examples of TGET and TPUT Macro Instructions 


The following coding examples show different ways to use the TGET and 
TPUT macro instructions. 

EXAMPLES OF BOTH TPUT AND TGET USING THE DEFAULT VALUES 

Figure 75 shows both a TPUT and a TGET macro instruction. They both 
take the default values; that is, the TPUT macro instruction defaults to 
EDIT, WAIT, NOHOLD, and NOBREAK; and the TGET macro instruction defaults 
to EDIT and WAIT. 



Figure 75. Coding Example --of TPUT and TGET Macro Instructions Using 
the Default Values 


182 Guide to Writing a TMP or a CP (Release 21.6) 















































The program issuing the TGET macro instruction will not be given 
control until a line of data is returned. The default value is WAIT. 

The input buffer will be padded with blanks if less than 130 characters 
were entered; the default is EDIT. Remember that the actual length of 
the data in the input buffer is returned in register 1. 

EXAMPLE OF TPUT MACRO INSTRUCTION — BUFFER ADDRESS AND BUFFER LENGTH IN 
REGISTERS. 

In the coding example shown in Figure 76, the output message buffer 
address and length are loaded into registers, and those registers coded 
as operands in the TPUT macro instruction. 

You might want to do this when, for example, the TPUT macro 
instruction is issued in a subroutine which receives, as parameters, a 
pointer to the message and the message length. 



Figure 76. Coding Example: TPUT Macro Instruction Buffer Address and 
Buffer Length in Registers 
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EXAMPLE OF THE TGET MACRO INSTRUCTION — REGISTER FORMAT 

Figure 77 shows the code necessary to issue a register format TGET macro 
instruction. The buffer length, buffer address, and the option flags 
are loaded into registers zero and one. Note that the flag byte in" 
register one has been set to binary 10000001, indicating that this is a 
TGET macro instruction requesting ASIS processing. This means that only 
minimal editing will be performed on the input line. 



Figure 77. Coding Example: TGET Macro Instruction Register Format 


184 Guide to Writing a TMP or a CP (Release 21.6) 




























































Using Terminal Control Macro Instructions 


The following macro instructions allow a command processor to control 
terminal functions and attributes. (These macro instructions were 
formerly documented in IBM System/360 Operating System: Supervisor and 
Data Management Macro Instructions , GC28-6647.) They are listed, then 
described in detail. 


Macro Instruction Function 


GTSIZE 

RTAUTOPT 

SPAUTOPT 

STATTN 

STATUS 

STAUTOCP 

STAUTOLN 

STBREAK 

STCC 

STCLEAR 

STCOM 

STSIZE 

STTIMEOU 

TCLEARQ 


Get Terminal Line Size 

Restart Automatic Line Numbering or Character 
Prompting 

Stop Automatic Line Numbering or Character 
Prompting 

Set Attention Simulation 

Change Subtask Status 

Start Automatic Character Prompting 

Set Automatic Line Numbering 

Set Break 

Specify Line-Deletion and Character-Deletion 
Characters 

Set Display Clear Character String 
Set Inter-Terminal Communication 
Set Terminal Line Size 
Set Timeout Feature 
Clear Buffers 


Some of the terminal control macro instructions may be safely coded 
in a user-written command processor. They ares 


GTSIZE 

RTAUTOPT 

SPAUTOPT 

STATUS 

STAUTOCP 

STAUTOLN 

STSIZE 

TCLEARQ 

The other macro instructions, intended for system use, are not 
recommended for inclusion in user-written command processors. These 
macros are used in the IBM-supplied PROFILE and TERMINAL commands. 
Inappropriate use of the following macros can cause terminal errors: 

STATTN 

STBREAK 

STCC 

STCLEAR 

STCOM 

STTIMEOU 

GTSIZE — Get Terminal Line Size 

Use the GTSIZE macro instruction to determine the current logical line 
size of the user's terminal. If the terminal is a display station, use 
the GTSIZE macro instruction to determine the size of the display 
screen. 

When the GTSIZE macro instruction is issued in a time sharing 
environment, the logical line size of the user's terminal (that is, the 
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maximum number of characters per line) is returned in register 1. If 
the terminal is a display station, the line size is returned in register 
1 and the screen length (that is, the maximum number of lines per 
display) is returned in register 0. If the terminal is not a display 
station, register 0 will contain all zeros. The GTSIZE macro 
instruction is ignored if TSO is not active when the macro instruction 
is issued. 

Figure 78 shows the format of the GTSIZE macro instruction. 

r- t- 1 

| [symbol] | GTSIZE j 

L _i_ J 

Figure 78. The GTSIZE Macro Instruction 

When control is returned to the user, register 15 contains one of the 
following return codes: 


Hexadecimal Code Meaning 

00 Successful. The contents of registers 

0 and 1 are described above. 

04 Parameter(s) specified. No parameter(s) 

should be coded. 


RTAUTOPT — Restart Automatic Line Numbering or Character Prompting 

Use the RTAUTOPT macro instruction to restart either the automatic line 
numbering feature or the automatic character prompting feature. (The 
feature was suspended when the terminal user caused an attention 
interruption or entered a null line of input.) Since only one of these 
features can be used at a time, the restarted feature is the one that 
was suspended. (See the STAUTOLN macro instruction for a description of 
the automatic line numbering feature and the STAUTOCP macro instruction 
for a description of the automatic character prompting feature.) 

When this macro instruction is used to restart automatic line 
numbering, the first line number assigned after line numbering is 
restarted is the same line number that would have been assigned to the 
next line of terminal input if automatic line numbering had not been 
suspended. 

If the application program is creating a line numbered data set, use 
of the STAUTOLN macro to specify the starting number is recommended when 
restarting automatic line numbering. This will insure that the 
application's numbers are still in synchronization with the system's. 

The RTAUTOPT macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 79 shows the format of the RTAUTOPT macro instruction. 

r- t-*--—-- 1 

| [symbol] | RTAUTOPT I 

L-X-J 

Figure 79. The RTAUTOPT Macro Instruction 

When control is returned to the user, register 15 contains one of the 
following return codes: 
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Hexadecimal Code 


Meaning 


00 Successful. Either automatic line numbering or 

automatic character prompting has been 
restarted. 

04 Parameter(s) specified. No parameter(s) should 

be coded. 

08 Invalid request. Either automatic line 

numbering or automatic character prompting was 
never started or never suspended, or a SPAUTOPT 
macro instruction has been issued to stop 
automatic line numbering or automatic character 
prompting. 

SPAUTOPT — Stop Automatic Line Numbering or Character Prompting 

Use the SPAUTOPT macro instruction to stop either the automatic line 
numbering feature or the automatic character prompting feature. Since 
only one of these features can be used at a time, the active feature is 
the feature that is stopped. (See the STAUTOLN macro instruction for a 
description of the automatic line numbering feature, and the STAUTOCP 
macro instruction for a description of the automatic character prompting 
feature.) 

The system can suspend automatic prompting when the terminal user 
causes an attention interrupt or enters a null line of input. This 
macro should then be issued by the application program in its attention 
exit, or as the result of a zero length input line received via TGET. 
When stopped by the SPAUTOPT macro, prompting cannot be restarted by use 
of the RTAUTOPT macro. Prompting must be restarted by the STAUTOLN or 
STAUTOCP macro. 

The SPAUTOPT macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 80 shows the format of the SPAUTOPT macro instruction. 

r- t-t- 1 

| [symbol] | SPAUTOPT | j 

l -x_x-j 

Figure 80. The SPAUTOPT Macro Instruction 

When control is returned to the user, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 

00 Successful. Either automatic line numbering or 

automatic character prompting has been stopped. 

04 Parameter(s) specified. No parameter(s) should 

be coded. 

08 Invalid request. Either automatic line 

numbering or automatic character prompting was 
never started. 
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STATTN — Set Attention Simulation 


Use the STATTN macro instruction to specify how a terminal user can 
interrupt the execution of his program without using an Attention key. 
The TERMINAL command issues the STATTN macro when the terminal user 
requests that simulated attention be set up. 

When the STATTN macro instruction assigns a value to an operand, that 
value remains in effect until another STATTN macro instruction assigns a 
new value to the operand, or until the terminal user logs off. Issuing 
the STATTN macro instruction without specifying any operands results in 
a NOP instruction. 

The STATTN macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 81 shows the format of the STATTN macro instruction. Each of 
the operands is explained following the figure. If an operand is not 
specified, its current status is not changed. 
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Figure 81. The STATTN Macro Instruction 


LINES= 

indicates the output line count (if any) that determines when a 
terminal user can interrupt the execution of his program. 

integer 

specifies an integer from 1 through 255. This integer 
indicates the number of consecutive lines of output that can 
be directed to the terminal before the keyboard will unlock to 
let the terminal user interrupt the execution of his program. 

0 

indicates that output line count will not be used to determine 
when the terminal user can interrupt the execution of his 
program. 

If the LINES operand is coded for a display station, it is ignored. 
However, the display user may cause a simulated attention 
interruption at the bottom of the screen (i.e., after every 6, 12, 
or 15 lines of consecutive output, depending on screen size). 


TENS= 

indicates whether or not locked keyboard time will be used to 
determine when a terminal user can interrupt the execution of his 
program. 

integer 

specifies an integer from 1 through 255. This integer 
indicates the tens of seconds (that is, from 10 to 2550 
seconds) of locked keyboard time that can elapse before the 
keyboard will unlock to let the terminal user interrupt the 
execution of his program. 

0 

indicates that locked keyboard time will not be used to 
determine when the terminal user can interrupt the execution 
of his program. 
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INPUT= 

indicates whether or not a character string will be used to 
determine when a terminal user can interrupt the execution of his 
program. 

address 

specifies the address of a character string from one to four 
EBCDIC characters long, left-justified and padded to the right 
with blanks if less than four characters long. When this 
character string is encountered as the only data in a line, 
input processing is interrupted to let the program take an 
attention exit. (See the description of the STAX macro 
instruction.) This string will not be recognized if it is 
preceded by any other character(s), including line delete or 
character delete control characters. 


0 

indicates that no character string will be used to determine 
when the terminal user can interrupt the execution of his 
program. 

When control is returned to the user, register 15 will contain the 
following return code: 

Hexadecimal Code Meaning 

00 Successful 

04 Invalid request 

STATUS — Change Subtask Status 

Use the STATUS macro instruction to change the dispatchability status of 
one or all of a program^ subtasks. One use of the STATUS macro 
instruction is to restart subtasks that were stopped when an attention 
exit routine was entered. (See the description of the STAX macro 
instruction in "Attention Interruption Handling - the STAX Service 
Routine.") 

The STATUS macro instruction is used in both time sharing and 
non-time sharing environments. 

Figure 82 shows the format of the STATUS macro instruction. Each of 
the operands is explained following the figure. 

f-T-T-1 

| [symbol] | STATUS | (START\[,TCB=subtask tcb address] | 

| | | (STOP ) | 

L- JL _X_J 

Figure 82. The STATUS Macro Instruction 
START 

indicates that the STOP/START count in the task control block 
specified in the TCB operand will be decremented by 1. If the TCB 
operand is not coded, the STOP/START count is decremented by one in 
all the subtask control blocks of the originating task. 


STOP 

indicates that the STOP/START count in the task control block 
specified in the TCB operand will be incremented by 1. If the TCB 
operand is not coded, the STOP/START count is incremented by 1 in 
the task control blocks for all the subtasks of the originating 
task. 
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TCB= 


is the address of a fullword on a fullword boundary that contains 
the address of the task control block that is to have its 
STOP/START count adjusted. If this operand is specified using 
register notation, the address of the task control block (not the 
address of the fullword) must have been previously loaded into the 
specified register. If this operand is not specified, the 
STOF/START count is adjusted in the task control blocks for all the 
subtasks of the originating task. 

Control is returned to the instruction following the STATUS macro 
instruction. When control is returned, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 

00 Successful 

04 The specified task control block does not 

belong to a subtask of the originating task. 

The STATUS macro instruction was ignored. 

STAUTQCP -- Start Automatic Character Prompting 

Use the STAUTOCP macro instruction to start automatic character 
prompting. Automatic character prompting signals the terminal user when 
the system is ready to accept input from the terminal. This signal 
consists of putting out at the terminal either an underscore and a 
backspace or a period and a carriage return, depending on the type of 
terminal being used. The STAUTOCP macro has no effect with a 2260 or 
2265 display station, since the terminal user is always prompted for 
input by the M start-of-message n symbol. 

This macro instruction can be used to have the system automatically 
prompt the user for input. It is used, for example, by the INPUT 
subcommand of the EDIT command. 

Once started, automatic prompting is handled as follows: When the 
system has received a line of input, it immediately sends back to the 
terminal the next character prompt. If the program should send output 
while automatic prompting is in effect, the prompt will be repeated 
after all output has been set to the terminal. For example: 

line of input 

OUTPUT MSG FROM PROGRAM 


Automatic prompting is designed to be used by a program operating in 
input mode (i.e. , issuing successive TGET macros). 

The system suspends automatic prompting when the terminal user causes 
an attention interruption or when he enters a null (nonprinting) line of 
input. The application program then takes appropriate action in an 
attention exit routine, or after receiving a zero length input via the 
TGET macro instruction. The application program can stop the prompting 
or line numbering function via SPAUTOPT, or restart the function via 
STAUTOCP. 

The STAUTOCP macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 
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Figure 83 shows the format of the STAUTOCP macro instruction. 

r-r- t- 1 

| [symbol] | STAUTOCP | | 

l--L_X-J 

Figure 83. The STAUTOCP Macro Instruction 

When control is returned to the user, register 15 contains one of the 
following return codes; 

Hexadecimal Code Meaning 

00 Successful. 

04 Parameter(s) specified. No parameter(s) should be 

coded. 

STAUTOLN — Start Automatic Line Numbering 

Use the STAUTOLN macro instruction to start automatic line numbering. 
Automatic line numbering prints a line number at the beginning of each 
line. 

This macro instruction can be used to have the system automatically 
prompt the user for input. It is used, for example, by the INPUT 
subcommand of the EDIT command. 

Once started, automatic line numbering is handled as follows; When 
the system has received a line of input, it immediately sends back to 
the terminal the next line number. If the program should send output 
while automatic line numbering is in effect, the line number will be 
repeated after all output has been set to the terminal. For example; 

00030 line of input 

00040 OUTPUT MSG FROM PROGRAM 

00040 

Automatic line numbering is designed to be used by a program operating 
in input mode (i.e., issuing successive TGET macros). 

The system prints a new line number for each line of input received. 
The current line number maintained by the system is decremented 
appropriately whenever the input queue is cleared by a TCLEARQ macro or 
as the result of an attention interruption. The application program is 
responsible for numbering the lines independently, if it is creating a 
line numbered data set. The system line number is not available to the 
application program. 

The system suspends automatic line numbering when the terminal user 
causes an attention interruption or when he enters a null (nonprinting) 
line of input. The application program then takes appropriate action in 
an attention exit routine, or after receiving a zero length input via 
the TGET macro instruction. The application program can stop the line 
numbering function via SPAUTOPT, or restart the function via STAUTOLN or 
RTAUTOPT. You should use STAUTOLN rather than RTAUTOPT to restart 
automatic line numbering, if the application program is numbering the 
input lines it receives. This choice will insure that the program's 
numbers are still in synchronization with the system's numbers. 

The STAUTOLN macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 
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Figure 8 4 shows the format of the STAUTOLN macro instruction. Each 
of the operands is explained following the figure. 

r- t-t—-------- *—i 

| [symbol] | STAUTOLN | S=address I=address | 

L--L---JL-------J 

Figure 84. The STAUTOLN Macro Instruction 

s= 

indicates the address of a fullword that contains the number to be 
assigned to the first line of terminal input. This number can be 
any integer from 0 through 99,999,999. 

1 = 

indicates the address of a fullword that contains the increment 
value to be used when assigning line numbers to lines of terminal 
input. This number can be any integer from 0 through 99,999,999. 

When control is returned to the user, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 

00 Successful. A line number will be printed out at 

the beginning of each line of input. 

04 Invalid parameter(s) specified. 

STBREAK — Set Break 

Use the STBREAK macro instruction to indicate whether the transmit 
interrupt feature on an IBM 1050 terminal or on an IBM 2741 terminal 
will be used or suppressed. The transmit interrupt feature lets 
terminal output processing interrupt terminal input processing. 

The TERMINAL command issues this macro when the terminal user 
specifies the BREAK or NOBREAK operand of the command. 

The macro should be issued only when the terminal currently connected 
is a 1050 or a 2741 which has the transmit interrupt feature. 

Specifying STBREAK YES for a 1050 or 2741 without the transmit interrupt 
feature could result in loss of output or permanent error at the 
terminal. 

When the transmit interrupt feature is being used by the system, the 
terminal user can "type ahead" of his program, entering the next line 
while the previous one is being processed. All 33/35 teletypes are 
handled this way. 1050*3 and 2741’s that have been defined in the 
TSO-TCAM Message Control Program as having the transmit interrupt 
feature will be handled this way (unless STBREAK NO is specified). 

Terminal handling when the feature is in use is as follows. If no 
output is available for the terminal, and if there are sufficient TSO 
terminal buffers available, the keyboard will be unlocked to allow the 
user to enter input. If the user's program generates output (TPUT) 
before he has started to enter data, the read operation is halted and 
the break (transmit interrupt) feature can be used to lock the keyboard 
and condition the communications line to transmit output. If the user 
has already started to type when the TPUT is issued, the output will not 
be sent until he has finished that line of input. If, however, the TPUT 
had specified the BREAKIN option, the output message would interrupt any 
input in progress. If the application does not issue a TCLEARQ macro to 
flush the input buffer queue, the interrupted input will be printed out 
again after the output is sent, to let the user continue to type from 
the point where he had been interrupted. 
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When the transmit interrupt feature is not being used by the system, 
the terminal keyboard is unlocked only after the user's program has 
issued a TGET request for input. In this mode of operation, the 
terminal user cannot type ahead of his program, A TPUT with the BREAKIN 
option cannot interrupt input. The output will not be sent until the 
terminal user has completed entering his current input line. All 2260 
and 2265 display stations are handled in this way. All 1050*s and 
2741's which have been defined in the TSO-TCAM Message Control Program 
as not having the transmit interrupt feature will be handled this way. 

The STBREAK macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 85 shows the format of the STBREAK macro instruction. 


r- t- 

| [symbol] | STBREAK 

I I 

L- JL - 



Figure 85. The STBREAK Macro Instruction 


i 


j 


YES 

indicates that the transmit interrupt feature will be used. If 
neither YES nor NO is specified, YES is assumed. 

NO 

indicates that the transmit interrupt feature not be used. 

When control is returned to the user, register 15 will contain one of 
the following return codes: 


Hexadecimal Code Meaning 


00 


Successful. 


04 Invalid parameter. 

08 Invalid terminal type. This macro instruction 

should be issued only for the IBM 1050 terminal or 
the IBM 2741 terminal. 

STCC — Specify Terminal Control Characters 


Use the STCC macro instruction to specify what control characters will 
be used to delete a character or a line of terminal input. 


The PROFILE command issues this macro when a terminal user requests a 
new line or character deletion character. The PROFILE command also 
causes the newly defined characters to be included in the user's profile 
in the User Attribute Data Set (UADS). Each time the user logs on, the 
Terminal Monitor Program will issue the STCC macro, specifying the 
characters in the UADS at the start of the session. If the terminal 
user does not use the PROFILE command to change the line or 
character-deletion characters, the system-supplied defaults are always 
used, as described below. 


When the line-delete control character specified in the STCC macro 
instruction is encountered within a line of terminal input, the line 
control character and all the preceding characters in that line are 
deleted. When the character-delete control character specified in the 
STCC macro instruction is encountered within a line of terminal input, 
the character delete control character and the character immediately 
preceding it are deleted from the line. 
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When the user is logging on, he can delete a line or character by 
using the system-supplied defaults. The defaults, according to type of 
terminal, are as follows: 


Type of Terminal Desired Action 


Key(s) to be Pressed 


2741 and 1050 line deletion or 

character deletion 


Attention key and 
backspace 


33/35 Teletype 1 * line deletion or 

character deletion 


CTRL and X key (hex 'IS 1 ), 
back arrow (**-), or 
underscore (_), depending 
on keyboard. (Either key 
results in hex '6D'.) 


No defaults are defined for the 2260 or 2265 display stations, because 
the terminal user can use cursor control keys more effectively to delete 
characters or lines before the input is transmitted to the system. 

The STCC macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not motive whpn the macro 
instruction is issued. 


Figure 86 shows the format of the STCC macro instruction; each of the 
operands is explained following the figure. 


T T T [attnI r ixviir i 

| [symbol] | STCC J [^NATNJ ^,LD=(C , c , /J CD=\C i c , /J j 

Figure 86. The STCC Macro Instruction 

ATTN 

When this operand is in effect, hitting the Attention key after 
having typed data will only delete the current line. System 
response is !D. Automatic prompting is not turned off. The 
Attention key can then be hit again, without typing any input, to 
interrupt the program and turn off prompting. When this operand is 
not in effect, the Attention key will both delete a line of 

terminal input and interrupt the execution of the user's program. 

System response is !. or !I. 

NATN 

indicates that the Attention key will not be used to delete a line 
of terminal input. 

LD= 

indicates what character will be used for the line delete control 
character. (Do not specify both LD= and ATTN.) 

X'n*, where n is the hexadecimal representation of any EBCDIC 
character on the terminal keyboard, except the new line 
(NL) and carriage return (CR) control characters. If 
X* 00* is specified, the previously used line-delete 
control character is retained. If X'FF* is specified, no 
character will be used for the line-delete control 
character. If a character that does not appear on the 
terminal keyboard is specified, that character is rejected 
and no character is used to delete a line of terminal 
input. 

C*c f where c is the character representation of any EBCDIC 
character on the terminal keyboard. 


^Trademark of the Teletype Corporation. 
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CD= 

indicates what character will be used for the character delete 
control character. 

X f n* where n is the hexadecimal representation of any EBCDIC 

character on the terminal keyboard except the new line (NL) 
and carriage return (CR) control characters. If X'OO* is 
specified, the previously used character delete control 
character is retained. If X f FF* is specified, no character 
will be used for the character delete control character. 

If a character that does not appear on the terminal 
keyboard is specified, that character is rejected and no 
character is used to delete a character from a line of 
terminal input. 

C'c" where c is the character representation of any EBCDIC 
character on the terminal keyboard. 

When control is returned to the user, the low-order byte of register 
0 contains the former line delete control character. If X’FF* appears 
in the low-order byte of register 0, there is no former line delete 
control character. If X'80 f appears in the high-order byte of register 
0, ATTN has been specified for line deletion. 

The low-order byte of register 1 contains the former character delete 
control character. If X'FF* appears in the low-order byte of register 
1, there is no former character delete control character. 

Register 15 contains one of the following return codes: 


Hexadecimal Code 

Meaning 


00 

Successful. 


04 

Invalid parameters specified. 


08 

Invalid request. Specified character does not 
appear on the terminal keyboard or ATTN was 
specified for a terminal that does not have an 
attention key. 


STCLEAR — Set Display Clear Character String 

Use the STCLEAR macro instruction to specify the character string that 
will be used to request that a 2260 or 2265 display station screen be 
erased. The TERMINAL command issues this macro when the user specifies 
the character string he wants. 

The STCLEAR macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 87 shows the format of the STCLEAR macro instruction. Each of 
the operands is explained following the figure. 


r - T - T -1 

| | | Jaddress] j 

| [symbol] | STCLEAR | STRING=\ 0 / | 

L_X_X_J 


Figure 87. The STCLEAR Macro Instruction 
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STRING= 

indicates the address of a one-to four character string that will 
be used to request that the display station screen be erased. This 
character string must be left-justified and padded on the right 
with blanks, if necessary. If 0 is specified, no character string 
will be used to erase the screen. 

When control is returned to the user, register 15 contains one of the 
following return codes: 


Hexadecimal Code 

Meaninq 

00 

Successful. 

04 

Invalid parameter. 

08 

Invalid terminal type. The terminal is not a 
display station. 


STCOM — Set Inter-Terminal Communication 


Use the STCOM macro instruction to specify whether or not a terminal 
will accept messages from other terminals, or low priority messages from 
the system operator. High priority operator messages are always sent to 
the terminal. The PROFILE command issues this macro when the user 
specifies the INTERCOM or NOINTERCOM operand of the command. 

The STCOM macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 88 shows the format of the STCOM macro instruction. 

r - T - T - 

I l l to 

I [symbol] | STCOM | NO 

l _r_i_r_ 

Figure 88. The STCOM Macro Instruction 
YES 

indicates that the terminal will accept messages from other 
terminals. If neither YES nor NO is specified, YES is assumed. 



NO 

indicates that the terminal will not accept messages from other 
terminals. 

When control is returned to the user, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 

00 Successful. 

04 Invalid parameter specified. 

STSIZE — Set Terminal Line Size 


Use the STSIZE macro instruction to set the logical line size of the 
time sharing terminal. If the terminal is a display station, the STSIZE 
macro instruction is used to set the screen size. 

The TERMINAL command issues this macro instruction when the user 
specifies the LINESIZE or SCREEN operands of the command. 


196 Guide to Writing a TMP or a CP (Release 21.6) 





The STSIZE macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 89 shows the format of the STSIZE~macro instruction each of 
the operands is explained following the figure. 

r - T - T - - ---1 

| | | j SIZE=number l |,LINE=number | j 

| [symbol] | STSIZE | (SIZELOC=addressJ ,LINELOC=address | 

l _x_x_r_ d _j 

Figure 89. The STSIZE Macro Instruction 
SIZE 

specify the logical line size of the terminal in characters. If 
the logical line size requested is greater than the mechanical line 
size of the terminal, the last character in the line may be 
repeatedly typed over. Specifying a size greater than 255 will 
give unpredictable results. 

SIZELOC 

specify the address of a word containing the logical line size of 
the terminal in characters. 


LINE 

specify the number of lines that can appear on the screen of a 
display station terminal. 


LINELOC 

specify the address of a word containing the number of lines that 
can appear on the screen of a display station terminal. 

Note : If the terminal is a display station, either the LINE or 

LINELOC operand must be specified. If the terminal is not a 
display station, neither operand should be specified. 


Defaults by terminal type are as follows: 


Terminal Type 


Line Size, Number of Lines, or Screen Size 


2741 

1050 

33/35 Teletype* 
2260,2265 


120 

120 

72 

12x80, 12x40, 6x40, 15x64 - as specified by the 

installation in the TSO-TCAM Message Control 
Program. 


^Trademark of the Teletype Corporation. 
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When control is returned to the user, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 


00 Successful, 

04 Invalid parameter specified, 

08 Invalid LINE, LINELOC, SIZE, or SIZELOC operand, as 

follows: 

1. The LINE or LINELOC operand was specified for 
any terminal except a display station. (An 
operand value of zero is not an error, and has 
the same effect as omitting the operand.) 

2. The LINE or LINELOC operand was omitted, or 
specified as zero, for a display station. 

3. The SIZE or SIZELOC operand was omitted, or 
specified as zero, for any terminal type. 

0C The dimensions specified for a display station do 

not correspond to known existing screen size. 
Incorrect screen management can result. 


STTIMEOU — Set Timeout Feature 


Use the STTIMEOU macro instruction to specify whether the 1050 terminal 
has the optional text timeout suppression feature. The macro 
instruction allows 1050's, with or without the feature, to call in via 
the same switched line, with any 1050 being handled initially as if it 
did not have the feature. 

A 1050 without the text timeout suppression feature operates as 
follows: When the PROCEED light is on and the keyboard is unlocked, the 

terminal will "timeout," that is, the keyboard will lock if the user 
does not type input for approximately 20 seconds. The system 
subsequently responds to the timeout by restoring the keyboard so that 
the user may continue. The user can prevent the timeout by periodically 
pressing the SHIFT key. 

A 1050 with the text timeout suppression feature operates as follows: 
The keyboard does not lock if the user does not type input within 20 
seconds. The system can therefore use the Read Inhibit channel command, 
which does not timeout within 28 seconds, in contrast to the Read 
channel command that does timeout. (Note: If the system is directed to 
use the Read Inhibit channel command for a 1050 that does timeout, the 
terminal may be locked out of the system.) 

Until the STTIMEOU macro instruction is issued, 1050 terminals are 
handled as per the definition provided in the TSO TCAM Message Control 
Program. If the currently connected terminal has the text timeout 
suppression feature, STTIMEOU NO can be issued to direct the system to 
use Read Inhibit rather than Read channel commands. (STTIMEOU NO should 
not be issued for a 1050 that does not have the text timeout suppression 
feature. This specification could cause the terminal to be locked out 
of the system.) 

The TERMINAL command processor issues the STTIMEOU macro instruction 
when the user specifies the TIMEOUT or NOTIMEOUT operand of the TERMINAL 
command. The STTIMEOU macro instruction will remain in effect until the 
user logs off. 
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The STTIMEOU macro instruction should be issued only when an IBM 1050 
terminal is being used. Terminals which are equivalent to the one 
explicitly supported may also function satisfactorily. The customer is 
responsible for establishing equivalency. IBM assumes no responsibility 
for the impact that any changes to the IBM-supplied products or programs 
may have on such terminals. 

The STTIMEOU macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 

Figure 90 shows the format of the STTIMEOU macro instruction. 



| [symbol] | STTIMEOU | NO j 

L_ JL _X___ ± _J 

Figure 90. The STTIMEOU Macro Instruction 


YES 

indicates that IBM 1050 terminal does timeout. It does not have 
the text timeout suppression feature. If the operand is omitted, 
the default is YES. 

NO 

indicates that the IBM 1050 terminal does not timeout. The 1050 
does have the text timeout suppression feature. 

When control is returned to the user, register 15 contains one of the 
following return codes: 


Hexadecimal Code 

Meaning 

00 

Successful. 

04 

Invalid parameter specified. 

08 

Invalid terminal type. This macro instruction 
applies to the IBM 1050 terminal only. 

TCLEARQ — Clear 

Buffers 


TCLEARQ enables the user to throw away "typed ahead" input or unsent 
output. This clearing of the buffers lets the command processor 
resynchronize with the terminal user. 

For example, when a command processor analyzes the specified operands 
in a line of input and discovers missing or invalid parameters, it 
issues a TCLEARQ INPUT before sending a prompting message to the user. 
This insures that the command processor will receive a line of input 
entered after the terminal user has seen the prompting message. 

When the TCLEARQ macro instruction is issued to clear the input 
buffers, all the input that has been entered at the terminal but has not 
yet been processed by the foreground job is purged. To ensure 
synchronization, the terminal keyboard is locked until the next TGET 
macro is issued. 

When the TCLEARQ macro instruction is issued to clear the output 
buffers, all the output that has been processed by the foreground job 
but not yet printed out at the terminal is purged. 

The TCLEARQ macro instruction is used only in a time sharing 
environment. It is ignored if TSO is not active when the macro 
instruction is issued. 
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The TCLEARQ macro instruction is written as follows: 


Figure 91 shows the format of the TCLEARQ macro instruction; each of 
the operands is described following the figure. 

r- r --- t“---*---1 

i | | [INPUT 1 | 

j [symbol] j TCLEARQ | OUTPUT j 

L_ J _j_ t _ i _J 

Figure 91. The TCLEARQ Macro Instruction 
INPUT 

indicates that all input currently in the terminals input buffer 
queue will be lost, including the input line currently being 
entered, if any. If neither INPUT nor OUTPUT is specified, INPUT 
is assumed. 

OUTPUT 

indicates that all the output for this terminal that is currently 
in the terminal's output buffer queue will be purged, except for 
output messages that have begun to appear at the terminal, or 
messages from other terminals or the system operator. (Such 
messages are sent via the TPUT TJID macro instruction.) 

When control is returned to the user, register 15 contains one of the 
following return codes: 

Hexadecimal Code Meaning 

00 Successful 

04 Invalid parameter (s) specified 
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Command SCAN and PARSE -- Determining the Validity 
of Commands 


If you write your own command processors to run under TSO, you will need 
a method of determining whether any command name or subcommand name 
entering the system is valid, and whether the operands following the 
command are syntactically correct. Command Scan and Parse are two 
service routines provided within TSO, which perform those functions. 

Command Scan scans the command buffer for commands. Parse scans the 
command buffer for operands. In general. Command Scan is invoked by a 
Terminal Monitor Program and Parse is invoked by a command processor. 
Command Scan may also be invoked by the TEST Program or by any command 
processors that process subcommands. 

Both of these service routines are linked to; their entry points are: 

Service Routine Entry Point 

Command Scan IKJSCAN 

Parse IKJPARS 


Sequence of Operations 

If you use Command scan and Parse within a TMP or Command Processor, the 
sequence of operations is as follows: 

1. Your Terminal Monitor Program or Command Processor gets a line of 
input which may contain a command and its parameters. 

2. Your Terminal Monitor Program or Command Processor, links to 
Command Scan (IKJSCAN) and passes it a parameter list containing, 
among other things, the address of the command buffer. 

3. Command Scan scans the buffer for a command name, syntax checks the 
command name if you request it, updates the command buffer offset 
field to point to the command operands (if any), and returns 
control to the calling program. 

4. The calling program receives the address of the command name and 
gives control to the appropriate command processor or subcommand 
processor. 

5. The command processor links to Parse (IKJPARS) and passes it 
parameter lists containing, among other things, the syntactical 
structure of the command operands, and the address of the buffer. 

6. Parse scans the buffer for operands, builds a list describing the 
operands found, and returns control to the calling program. 

7. The command processor processes the command according to the 
operands received. 

8. When the command processor terminates, it returns control to the 
Terminal Monitor Program and the sequence is repeated. 


This section discusses: 

• Using the Command Scan Service Routine. 

• Using the Parse Service Routine. 
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Using the Command Scan Service Routine (IKJSCAN) 

Command Scan scans the command buffer for commands. In general, Command 
Scan is linked to by a Terminal Monitor Program, but it may also be 
invoked by the TEST program or by any command processors that process 
subcommands. 

Command scan scans a command within the command buffer and performs 
the following functions: 

1. It translates all lower case characters within the command name to 
upper case. 

2. It resets the offset pointer in the command buffer to point to the 
first non-blank character in the operand field, if a valid operand 
is present. If a valid operand is not present, the offset pointer 
points to the end of the buffer. 

3. It returns a pointer to the command name, the length of the command 
name, and a code explaining the results of its scan to the calling 
routine. 

4. It optionally, at your request, syntax checks the command name. 


This topic discusses: 

• Command Name Syntax 

• The Parameter List Structure Required by Command Scan. 

• The Command Scan Parameter List. 

• Flags Passed to Command Scan. 

• The Command Scan Output Area. 

• The Operation of the Command Scan Service Routine. 

• The Results of the Command Scan. 

• Return Codes from Command Scan. 


COMMAND NAME SYNTAX 

If you write your own command processor, and you intend to use the 
Command Scan service Routine to check for a valid command name, your 
name must meet the following syntax requirements: 

• The first character must be an alphabetic or a national character. 

• The remaining characters must be alphameric. 

• The length of the command name must not exceed eight characters. 

• The command delimiter must be a separator character. 

• The name should include one or more numerals. Since no IBM-Supplied 
Command Names include numerals, your command name will be unique. 


202 Guide to Writing a TMP or a CP (Release 21.6) 



THE PARAMETER LIST STRUCTURE REQUIRED BY COMMAND SCAN 

Before you LINK to the Command Scan service routine, you must create the 
parameter structure shown in Figure 92. You then place the address of 
the Command Scan Parameter List (CSPL) into general register 1, set the 
flags in the Flag word, and link to IKJSCAN, the Command Scan service 
routine. 


General 
Register 1 



Figure 92. The Parameter List Structure Passed to Command Scan 
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The Command Scan Parameter List 


The Command Scan Parameter List (CSPL) is a six-word parameter list 
containing addresses required by the Command Scan routine. In order to 
ensure the reenterability of the calling program, the CSPL should be 
built in subpool 1 in an area obtained by the calling program with the 
GETMAIN macro instruction. 

The CSPL is defined by the IKJCSPL DSECT• Figure 93 shows the format 
of the Command Scan Parameter List. 


Flags Passed to Command Scan 

The flag word built in subpool 1 and pointed to by the fourth word of 
the CSPL, is obtained and freed by the calling routine. Only the first 
byte of the field is used by the Command Scan service routine; the 
remaining three bytes are reserved. Set the flag byte before linking to 
the Command Scan routine to indicate whether or not you want the command 
to be syntax checked. The flag byte has the following meanings: 

X'OO' Syntax Check the command name. 

X' 80' Do not syntax check the command name. 

The Command Scan Output Area 

The Command Scan Service routine returns the results of its scan to the 
calling program by filling in a two word Command Scan Output Area 
(CSOA) • The CSOA must be obtained and freed by the calling program. It 
must be located in subpool 1 and its address stored into the fifth word 
of the Command Scan Parameter List before your program links to IKJSCAN. 


Number of 
Bytes 


Field 


Contents or Meaning 


-H 


CSPLUPT 


The address of the User Profile Table. 
Appendix A.) 


(See 


+ - 


CSPLECT 


CSPLECB 


The address of the Environment Control Table. 
(See Appendix A.) 

The address of the Command Processor's Event 
Control Block. (Required if Command Scan is 
called by a command processor to scan a 
subcommand; zeros if Command Scan is called 
by the TMP.) 


CSPLFLG 


CSPLOA 


The address of a fullword, obtained via the 
GETMAIN macro instruction by the routine 
linking to Command Scan, and located in 
subpool 1. The first byte of the word 
pointed to contains flags set by the calling 
routine; the last three bytes are reserved. 

A - 

The address of an 8-byte Command Scan Output 
Area, located in subpool 1. The output area 
is obtained by the calling routine via a 
GETMAIN macro instruction. It is filled by 
the Command Scan service routine before it 
returns control to the calling routine. (See 
Figure 92.) 


CSPLCBUF |The address of the Command buffer. 
- x - 


Figure 93. The Command Scan Parameter List 
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The CSOA is defined by the IKJCSOA DSECT. Figure 94 shows the format 
of the Command Scan Output Area. 


r T i 

Number of | 

Bytes | Field 

i 

Contents or Meaning 

T 1 

4 | CSOACNM 

1 

1 

l 4^ -1 

The address of the command name if the 
command name is present and valid. Zero 
otherwise. 

2 | CSOALNM 

1 

Length of the command name if the command 
name is present and valid. Zero otherwise. 

1 | CSOAFLG 

1 

1 

1 

_ _ I J 

A flag field. Command Scan sets these flags 
to indicate the results of its scan. See 
Figure 94 'Return from Command Scan - CSOA 
and Buffer Setting’. 

t 1 

i i 

Reserved. 


L-X-X-J 

Figure 94. The Command Scan Output Area 


THE OPERATION OF THE COMMAND SCAN SERVICE ROUTINE 

If you set the flags field in the flag word to X'80' — do not syntax 
check the command name — the command scan service routine merely scans 
the buffer to determine if it contains a question mark or a command. 

The first character in the command buffer is checked for a question mark 
whether or not syntax checking is requested. If it is a question mark, 
no further scanning is done. If it is not a question mark, the command 
name is considered to begin at the first non-separator character found, 
and end at the first command delimiter character found (See Figure 81). 

Command Scan translates any lower case letters in the command name to 
upper case, fills the Command Scan Output Area, updates the command 
buffer offset field, and returns to the calling program. 

If you have requested syntax checking (X’OO* in the flag field of the 
flag word), the command name must meet the syntax requirements, as 
follows: 

• The first character must be an alphabetic or a national character. 

• The remaining characters must be alphameric. 

• The length of the command name must not exceed eight characters. 

• The command delimiter must be a separator character. 

Figure 95 shows the various character types recognized by Command Scan. 
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RESULTS OF THE COMMAND SCAN 


The Command Scan service routine scans the command buffer and returns 
the results of its scan to the calling routine by filling the Command 
Scan Output Area, and by updating the offset field in the command 
buffer. Figure 96 shows the possible CSOA settings and command buffer 
offset settings upon return from the Command Scan service routine. 


Command Scan Output Area 


— + 


Command Buffer 


Flag | 


Meaning 


I 


Length Field 


Offset set to 2 


H 


X' 80 # 


h 


The command name is 
valid and the 
remainder of the 
buffer contains non¬ 
separator 
characters. 


-f 


Length of command name 


The first non¬ 
separator following 
the c ommand name. 


-H 


x f 40' 


The command name is 
valid and there are 
no non-separator 
characters 
remaining. 


Length of command name. 


The end of the 
buffer. 


X 1 20 1 


t— 


The command name is 
a question mark. 


Zero 


Unchanged. 


X'lO* 


h 


The buffer is empty 
or contains only 
separators. 


Zero 


The end of the 
buffer. 


-H 


X f 08'I The command name is 
syntactically 
invalid. 


Zero 


Unchanged. 


L_X_JL_ ± _J 

Figure 96. Return from Command Scan - CSOA and Command Buffer Settings 


RETURN CODES FROM COMMAND SCAN 

The Command Scan service routine returns the following codes in general 
register 15 to the program that invoked it: 

CODE (hex) Meaning 

0 Command Scan completed successfully. 

4 Command Scan was passed invalid parameters. 


Command Scan and Parse - Determining the Validity of Commands 207 












Using the Parse Service Routine (IKJPARS) 


The Parse service routine checks the syntax of command operands. To 
prepare for this, the command processor creates a Parameter Control List 

(PCL ) - a description of permissible operands, default values, text 

to be used when prompting, and, if present, the address of a validity 
checking subroutine. 


The command processor links to Parse, which scans and checks each 
operand against the entries (called PCEs: Parameter Control Entries) in 
the PCL. In turn. Parse builds and returns results of the scan to the 
command processor in a Parameter Descriptor List (PDL), whose entries 
(called PDEss Parameter Descriptor Entries) contain pointers to data 
set names, indications of specified options, or pointers to the 
subfields entered with the command operands. 


The command processor uses the IKJPARMD DSECT to refer to the PDL. 

The coiiuiiand processor specifies the IKJPARMD DSECT at the time it issues 
the PARSE macro instructions to build the PCL. The labels used by the 
command processor on the various Parse macro instructions become the 
symbolic addresses of the fields in the IKJPARMD DSECT. 


Figure 97 depicts a command processors use of the Parse macro 
instructions, the Parse service routine, and the IKJPARMD DSECT. 
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Command Buffer 


Command Name 


Parameter 1 


Parameter 2 


Parameter 3 


Command Processor 

0 Issues Parse macro 
instructions to build 
a PCL describing 
valid parameters 

• label 1 Macro 

• Iabel2 Macro 

• Iabel3 Macro 


© LINK to Parse 


Parse Service Routine 

^ 0 Compares PCE's to 
parameters in the 
Command Buffer. 


These macro 
instructions also 
create the 
IKJPARMD DSECT. 

IKJPARMD 

DSECT 

Habell | 


(7) Bui Ids 1 


(7) The Command 

Processor uses the 
IKJPARMD DSECT 
to access the various 
PDEs within the 
PDL. 


(7) Return to the Command Processor 




Figure 97. A Command Processor Using the Parse Service Routine 


Parse service routine support consists of the following: 


1. The following set of macro instructions: 

IKJPARM Begins the Parameter Control List and establishes a 
symbolic reference for the Parameter Descriptor List. 

IKJPOSIT Builds a Parameter Control Entry. This PCE describes a 
positional parameter that contains delimiters recognized by the 
Parse Service routine; but not including the positional parameters 
described by the IKJTERM, IKJOPER, or IKJRSVWD macro instructions. 

IKJIDENT Also builds a Parameter Control Entry; however, this PCE 
describes a positional parameter that does not depend upon a 
particular delimiter. 
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IKJKEYWD Builds a Parameter Control Entry that describes a Keyword 
parameter. 

IKJNAME Describes the possible names that may be entered for a 
keyword or reserved word parameter, 

IKJTERM Builds a Parameter Control Entry. This PCE describes a 
positional parameter that may be a constant, statement number, or 
variable. 

IKJOPER Builds a Parameter Control Entry that describes an 
expression. An expression consists of three parts; two operands 
and an operator in the form: 

(operandl operator operand2) 

IKJRSVWD Builds a Parameter Control Entry. This PCE may be used 
with the IKJTERM macro instruction to describe a reserved word 
constant, with the IKJOPER macro instruction to describe the 
operator of an expression, or by itself to describe a reserved word 

I -- 

IKJSUBF Indicates the beginning of a keyword subfield description. 
IKJENDP Indicates the end of the PCL. 

IKJRLSA Releases any storage (allocated by the Parse service 
routine) that remains after Parse has returned control to the 
command processor. 

2. A program that checks the syntax of the command operands within the 
command buffer against the PCL and builds a PDL containing the 
results of the syntax check. 

| Parse also provides the following services which may be selected by 
the calling routine: 

• It translates the command operands to upper case. 

• It substitutes default values for missing operands. 

• It prompts the user at the terminal for missing positional 
parameters. 

• It passes control to an exit, supplied by the calling routine, to do 
further checking on a positional parameter. 

• It inserts implied keywords. 

J • It appends user-supplied second-level messages to prompting 
messages. 


This section describes: 

• Command Parameter Syntax 

• Using the Parse Macro Instructions to Define Command Syntax 

• The Parse Macro Instructions 

• Passing Control to the Parse Service Routine 

• Formats of the PDEs Returned by Parse 

• Additional Facilities Provided by Parse 

• An Example of Using the Parse Service Routine 

• Return Codes from the Parse Service Routine 
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COMMAND PARAMETER SYNTAX 


If you write your own command processors, and you intend to use the 
Parse service routine to determine which operands have been entered 
following the command name, your command parameters must adhere to the 
syntactical structure described in this section. 

Command parameters must be separated from one another by one or more 

I of the separator characters: blank, tabulation, or comma (See Figure 
95). The command parameters end either at the end of a logical line 
(carriage return), or at a semicolon. If the command parameters end 
with a semicolon, and other characters are entered after the semicolon 
but before the end of the logical line. Parse ignores that portion of 
the line that follows the semicolon. Parse returns no message to 
indicate this condition. 

I There are two types of command parameters recognized by the Parse 
service routine: (1) Positional parameters, or (2) Keyword parameters. 

Positional Parameters 


Positional parameters must be coded first in the parameter string, and 
they must be in a specific order. 

In general, the Parse service routine considers a positional 
parameter to be missing, if the first character of the parameter scanned 
is not the character expected. For instance, if a parameter is supposed 
to begin with a numeric character and Parse finds an alphabetic 
character in that position, the numeric parameter is considered missing. 
Parse then prompts for the missing parameter if it is required, 
substitutes a default value if one is available, or ignores the missing 
parameter if the parameter is optional. 

For the purpose of syntax checking, positional parameters are divided 
into parameters that include delimiters as part of their definition 
(delimiter-dependent parameters), and parameters that do not include 
delimiters as part of their definition (non-delimiter-dependent 
parameters). 
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DELIMITER-DEPENDENT PARAMETERS : Those parameters that include 
delimiters as part of their definition are called delimiter-dependent 
parameters. The Parse service routine recognizes the 
delimiter-dependent parameter syntaxes as shown in Figure 98. 


PARAMETER 


1. DELIMITER 


2. STRING 


3. VALUE 


4. ADDRESS 


5. PSTRING 


6. USERID 


7. DSNAME 


8. DSTHING 


9. QSTRING 


10. SPACE 


j Macro Instruction Used to Describe Parameter | 

-1 


11. CONSTANT 


12. VARIABLE 


13. STATEMENT NUMBER 


14. EXPRESSION 


15. RESERVED WORD 


IKJPOSIT 


IKJTERM 


IKJOPER 


IKJRSVWD 


Figure 98. Delimiter-Dependent Parameters 
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1. DELIMITER - It may be any character other than an asterisk* left 

parenthesis* right parenthesis* semicolon* blank* comma* 
tab* carriage return, or digit. A self-defining 
delimiter character is represented in this discussion by 
the symbol A • The delimiter parameter is used only in 
conjunction with the string parameter. 

2. STRING - A string is the group of characters between two alike 

self-defining delimiter characters* such as 

AstringA 

or* the group of characters between a self-defining 
delimiter character and the end of a logical line* such as 

A string 

The same self-defining delimiter character can be used to 
delimit two contiguous strings* such as 

A stringA string A 

or 

A stringAstring 

A null string* which indicates that a positional parameter has not been 
entered* is defined as two contiguous delimiters or a delimiter and the 
end of the logical line. If the missing string is a required parameter* 
the null string must be entered as two contiguous delimiters. Note that 
a string received from a prompt or a default must not include the 
delimiters. 


3. VALUE - A value consists of a character followed by a string 
enclosed in apostrophes* such as 

X 1 string 1 

The character must be an alphabetic or national character. 
The string may be of any length and may consist of any 
combination of enterable characters. If the ending 
apostrophe is left off the string* Parse assumes that the 
string ends at the end of the logical line. If Parse 
encounteres two successive apostrophes* it assumes them to 
be part of the string and continues to scan for a single 
ending apostrophe. The Parse service routine always raises 
the character preceding the first apostrophe to upper case. 
The value is considered missing if the first character is 
not an alphabetic or national character* or if the second 
character is not an apostrophe. 


4. ADDRESS - There are several forms of the address parameter. 

Absolute address - An absolute address consists of from one to six 
hexadecimal digits followed by a period. 

Relative address - A relative address consists of from one to six 
hexadecimal digits preceded by a plus sign. 
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I 


General register address - A general register address consists of a 
decimal integer in the range 0 to 15 followed by the letter R. R 
can be entered in either upper or lower case. 


Floating-point register address - A floating-point register address 
consists of an even decimal integer in the range 0 to 6 followed by 
the letter D (for double precision) or E (for single precision). 

The letter E or D can be entered in either upper or lower case. 

Symbolic address - A symbolic address consists of any combination, 
up to 31 characters in length, of the alphameric characters and the 
break character. The first character must be either an alphabetic 
or a national character. 

Qualified address - A qualified address has the following formats 

loadname.entryname.symbolic address 

or 

.relative address 

• loadname - any combination of alphameric characters up to eight 
characters in length, of which the first character is an 
alphabetic or a national character. 

• entryname - has the same syntax as a loadname, but it must be 
preceded by a period as illustrated in the example. 

• symbolic address - as defined above, but must be preceded by a 
period as illustrated in the example. 

® relative address - as defined above, but must be preceded by a 
period as illustrated in the example. 

Indirect address - An indirect address is an absolute, relative, 
symbolic, or general register address followed by from 1 to 255 
percent signs, such as: 

+A% 

The number of percent signs following the address indicate the 
number of levels of indirect addressing. In this example (+A%), the 
data is pointed to by the location pointed to by +A. 

Address expression - An address expression has the following format: 

addr[%...]+expression value(%...][+expression value[%...]] 

addr - represents an absolute, relative, symbolic, or general 
register address. If a general register address is used, then it 
must have indirect address notation, that is, it must be followed 
by at least one percent sign. 

expression value - consists of from one to six hexadecimal digits 
or one to six decimal digits followed by the letter N. The N can 
be in either upper or lower case. The expression values can be 
indirect. There is no limit to the number of expression values in 
the address expression. 

Note: Blanks are not allowed within any form of the address 

parameter. 
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1 5. PSTRING - A parenthesized string is a string of characters enclosed 
within a set of parentheses f such as: 

(string) 

The string may consists of any combination of characters of any 
length, with one restriction; if it includes parentheses, they 
must be balanced. The enclosing right parenthesis of a PSTRING 
can be omitted if the string ends at the end of a logical line. 

I A null PSTRING is defined as a left parenthesis followed by 

either a right parenthesis or the end of a logical line. 


1 6. USERID - A userid consists of an identification optionally followed 
by a slash and a password. The format is: 

identification [/password] 

identification - can be any combination of alphameric 
characters up to seven characters in length, the first of which 
must be an alphabetic or national character. 

password - can be any combination of alphameric characters up 
to eight characters in length, the first of which must be an 
alphabetic or national character. 

Blanks may be inserted between the identification and the 
slash, and between the slash and the password. 

If just the identification is entered. Parse does not prompt 
for the password. If the identification is entered followed by 

I a slash and no password. Parse prompts for the password by 

executing a PUTGET macro instruction specifying bypass mode, 
that is, the terminal user's reply will not print at the 
terminal. The terminal user can reply to a prompt for password 
by entering either a password or a null line. If the user 
enters a null line, PARSE builds the PDE and leaves the 
password field blank. 

| 7. DSNAME - The data set name parameter has three possible formats: 

dsname [(membername)] [/password] 

[dsname] (membername) [/password] 

'dsname [(membername)] ' [/password] 

dsname - may be either a qualified or an unqualified name. 

An unqualified name is any combination of alphameric characters 
up to eight characters in length, the first character of which 
must be an alphabetic or national character. 

A qualified name is made up of several unqualified names, each 
unqualified name separated by a period. A qualified name, 
including the periods, may be up to 44 characters in length. 

membername - one to eight alphameric characters, the first of 
which must be an alphabetic or a national character. 
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Notes PARSE considers the entire DSNAME parameter missing if 
the first character scanned is not an apostrophe, an alphabetic 
character, a national character, or a left parenthesis* 

If the slash and the password are not entered. Parse does not 
prompt for the password* If the slash is entered and not the 
password. Parse prompts for the password by executing a PUTGET 
macro instruction specifying bypass mode, i.e. , the terminal 
user's reply will not print at the terminal. 

8. DSTHING - A DSTHING is a dsname parameter as previously defined 

except that an asterisk can be substituted for an unqualified 
name or for each qualifier of a qualified name. PARSE 
processes the asterisk as if it were a DSNAME. The asterisk is 
used to indicate that all data sets at that particular level 
are considered. 

9. QSTRING - A quoted string is a string of characters enclosed within 

apostrophes, such as: 

'string' 

The string can consist of any length combination of characters, 
with one restriction: if the user wishes to enter apostrpohes 
within the string, two successive apostrophes must be entered 
for each single apostrophe desired; one of the apostrophes is 
removed during the parse. 

The ending apostrophe is not required if the string ends at the 
end of the logical line. 

A null quoted string is defined as two contiguous apostrophes 
or an apostrophe at the end of the logical line. 

10. SPACE - Space is a special purpose parameter; it allows a string 

parameter that directly follows a command name to be entered 
without a preceding self-defining delimiter character. The 
space parameter must always be followed by a string parameter. 
If the delimiter of the command name is a tab, the tab is the 
first character of the string. The string always ends at the 
end of the logical line. 

11. CONSTANT - There are several forms of the constant parameter. 

Fixed-point numeric literal - Consists of a string of digits (0 
through 9) preceded optionally by a sign ( + or -) , such as: 

+1234.43 

This literal may contain a decimal point anywhere in the string 
except as the rightmost character. The total number of digits 
cannot exceed 18. Embedded blanks are not allowed. 

Floating-point numeric literal - Takes the following form: 

+1234.56E+10 

This literal is a string of digits (0 through 9) preceded 
optionally by a sign (+ or -) and must contain a decimal point. 
This is immediately followed by the letter E and then a string 
of digits (0 through 9) preceded optionally by a sign (+ or -). 
Embedded blanks are not allowed. The string of digits 
preceding the letter E cannot be greater than 16 and the string 
following E cannot be greater than 2. 
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Non-numeric literal - Consists of a string of characters from 
the EBCDIC character set excluding the apostrophe and enclosed 
in apostrophes such as: 


•Numbers (1234567890) and letters are OK* 

The length of the string excluding apostrophes may be from 1 to 
120 characters in length. 

Figurative constant - Is one of a set of reserved words 
supplied by the caller of the Parse routine such as: 

testl23 

A figurative constant consists of a string of characters up to 
255 in length. Embedded blanks are not allowed. All 
characters of the EBCDIC character set are allowed except the 
blank, comma, tab, semicolon, and carriage return. 


12. VARIABLE - The following is the form of the variable parameter. 


[program-id. ]data-name 


{ OF) qualification 
INf 

(subscript) 


Data-name - consists of a maximum of 30 characters of the set: 

A through Z (Alphabetic) 

0 through 9 (Numeric) 

- (hyphen) 

such as: 

My-dataset-123 

The data-name cannot begin or end with a hyphen and must 
contain at least one alphabetic character. 


Program-id - Consists of the first eight characters of a 
program identifier followed by a period. The first character 
must be alphabetic (A through Z) and the remaining characters 
must be alphameric (A through Z or 0 through 9) such as: 

Here55.My-dataset 

Qualification - Is applied by placing after a data-name one or 
more data-name(s) preceded by the qualifiers IN or OF, such as: 

My-dataset-123 OF Your-dataset-456 

The number of qualifiers that can be entered for a data-name is 
limited to 255. 

Subscript - Consists of a data-name with subscripts enclosed in 
parentheses following the data-name such as: 

Your-dataset-456 (My-dataset-123) 

A separator between the data-name and the subscript is 
optional. Subscripts are a list of constants or variables. 
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The number of subscripts that can be entered for a data-name is limited 
to 3, such as 2 


Here55 (ABC def H15) 


A separator character between subscripts is required. 

13. STATEMENT NUMBER - The following is the form of a statement number. 

[program id.Jline number [.verb number] 

An example is: 

Here. 23.7 
Where: 

Program id - consists of the first eight characters of a 
program identifier followed by a period. The first character 
must be alphabetic (A through Z) and the remaining characters 
must be alphameric (A through Z or 0 through 9). 

Line number - consists of a string of digits (0 through 9) and 
that cannot exceed a length of 6 digits. 

Verb number - consists of one digit (0 through 9) that is 
preceded by a period. 

Embedded blanks are not allowed in a statement number. 

14. EXPRESSION - An expression takes the form: 

(operandl operator operand2) 

The operator in the expression shows a relationship between the 
operands, such as: 

(ABC equals 123) 

An expression must be enclosed in parentheses. An expression 
is defined by the IKJOPER macro. The operands are defined by 
the IKJTERM macro, and the operator by the IKJRSVWD macro 
instruction. 

15. RESERVED WORD - Has three uses depending on the presence or absence 

of operands on the IKJRSVWD macro instruction. The uses are: 

• When used with the RSVWD keyword of the IKJTERM macro 
instruction, the IKJRSVWD macro identifies the beginning of a 
list of reserved words anyone of which can be entered as a 
constant. 

• When used with the RSVWD keyword of the IKJOPER macro 
instruction, the IKJRSVWD macro identifies the beginning of a 
list of reserved words anyone of which can be an operator in 
an expression. 

• When used by itself, the IKJRSVWD macro instruction defines a 
positional reserved word parameter. 

Note : The IKJRSVWD macro instruction is followed by a list 

of IKJNAME macros that contain all of the possible reserved 
words used as figurative constants or operators. 
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POSITIONAL PARAMETERS NOT DEPENDENT ON DELIMITERS : A positional 
parameter that is not dependent on delimiters is parsed as a character 
string with restrictions on the beginning character, additional 
characters, and length. These restrictions are passed to the Parse 
service routine as operands on the IKJIDENT macro instruction. 

The Parse service routine recognizes the following character types a 

I the beginning character and additional characters of a 
non-delimiter-dependent positional parameter: 

ALPHA - Indicates an alphabetic or national character. 

NUMERIC - Indicates a number, (0-9). 

ALPHANUM - Indicates an alphabetic or national character or a number 
ANY - Indicates that the character to be expected can be any 

character other than a blank, comma, tab, semicolon, or carriage 
return. Right parenthesis must, however, be balanced by left 
parenthesis. 

An asterisk can be entered in place of any positional parameter that 
is not dependent on delimiters. 
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ENTERING POSITIONAL PARAMETERS AS LISTS OR RANGES : You may want to have 
some positional parameters of your command entered in the form of a 
list, a range, or a list of ranges. The macro instructions that 
describe positional parameters to the Parse service routine, IKJPOSIT, 
IKJTERM and IKJIDENT, provide a LIST and a RANGE operand. If coded in 
the macro instruction, they indicate that the positional parameters 
expected can be in the form of a list or a range. 


LIST 

Indicates to the Parse service routine that one or more of the same 
type of positional parameters may be entered enclosed in 
parentheses as follows: 

(positional-parameter positional-parameter ...) 

If one or more of the items contained in the list are to be entered 
enclosed in parentheses, both the left and the right parenthesis 
must be included for each of those items. 

The following positional parameter types may be used in the form of 
a list: 

• VALUE 

• ADDRESS 

• USERID 

• DSNAME 

• DSTHING 

• CONSTANT 

• STATEMENT NUMBER 

• VARIABLE 

• Any positional parameter that are not dependent upon delimiters. 

RANGE 

Indicates to the Parse service routine that two positional 
parameters are to be entered separated by a colon as follows: 

positional-parameter:positional-parameter 

The following positional parameter types may be used in the form of 
a range or a list of ranges: 

• ADDRESS 

• VALUE 

• CONSTANT 

• STATEMENT NUMBER 

• VARIABLE 

• Any positional parameter that is not dependent upon delimiters. 

If the user at the terminal wants to enter a parameter that begins with 
a left parentheses, and you have specified in either the IKJPOSIT or 
IKJIDENT macro instruction that the parameter can be entered as a list 
or a range, the user must enclose the parameter in an extra set of 
parentheses to obtain the correct result. 

For instance, if you have specified via the IKJPOSIT macro instruction 
that the DSNAME operand may be entered as a list, and the terminal user 
wishes to enter a dsname of the form: 

(membername)/password 

He must enter it as: 

((membername)/password) 
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Keyword Parameters 


Keyword parameters can be entered anywhere in the command as long as 
they follow all positional parameters. They may consists of any 
combination of alphameric characters up to 31 characters long, the first 
of which must be an alphabetic character. 

You describe keyword parameters to the Parse service routine with the 
IKJKEYWD, IKJNAME and IKJSUBF macro instructions. 

Keyword parameters can have other parameters associated with them. 
These parameters, known as subfields, must be enclosed in parentheses 
directly following the keyword. A subfield may contain positional as 
well as keyword parameters. In the following example posnl and kywd2 
are parameters in the subfield of keyword Is 

keywordl(posnl kywd2) 

The same syntax rules that apply to commands, apply within keyword 
subfields. 

• Keyword parameters must follow positional parameters. 

• Enclosing right parenthesis may be eliminated if the subfield ends 
at the end of a logical line. 

• The subfield may not contain unbalanced right parentheses. 

If a keyword, with a subfield in which there is a required parameter, 
is entered without the subfield. Parse prompts for the required 
parameter. The terminal user must not include the subfield parentheses 
when he enters the required parameter. 

If a subfield has a positional parameter, that can be entered as a 
list, and if this is the only parameter in the subfield, the list must 
be enclosed by the same parentheses that enclose the subfield, such as 

keyword(iteml item2 item3) 

where iteml, item2, and item3 are members of a list. 

If a subfield has, as its first parameter, a positional parameter 
that may be entered as a list, and there are additional parameters in 
the subfield, a separate set of parentheses is required to enclose the 
list, such as 

keyword((iteml item2 item3) param) 

where iteml, item2, and item3 are members of a list, and param is a 
parameter not included in the list. 
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USING THE PARSE MACRO INSTRUCTIONS TO DEFINE COMMAND SYNTAX 


A Command Processor using the Parse service routine must build a 
Parameter Control List (PCL) defining the syntax of acceptable command 
parameters. Each acceptable command parameter is described by a 
Parameter Control Entry (PCE) within the PCL. The Parse service routine 
compares the command parameters within the command buffer against the 
PCL to determine if valid command parameters have been entered. 

Parse returns the results of this comparison to the Command Processor 
in a Parameter Descriptor List (PDL). The PDL is composed of separate 
entries (PDEs) for each of the Command Parameters found in the command 
buffer. 

The Command Processor builds the PCL and the PCEs within it using the 
Parse macro instructions. These macro instructions generate the PCL and 
establish symbolic references for the PDL returned by the Parse service 
routine. 

| There are eleven Parse macro instructions. They are: 

• IKJPARM 

I ® IKJPOSIT 
• IKJTERM 
• IKJOPER 
• IKJRSVWD 
• IKJIDENT 
• IKJKEYWD 
• IKJNAME 
• IKJSUBF 
• IKJENDP 
• IKJRLSA 

These macro instruction perform the following functions: 

1. The IKJPARM macro instructions begins the PCL CSECT and the PDL 
DSECT , and provides symbolic addresses for both. 

J 2. The IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD, IKJIDENT, IKJKEYWD, 

IKJNAME 9 and IKJSUBF macro instructions describe the positional and 
keyword parameters valid for the command processor. These macro 
instructions expand into the PCEs required by the Parse service 
routine during its scan of the command buffer. The label fields of 

( these macro instructions are used as labels within the DSECT that 
maps the PDL returned by the Parse service routine. 

3. The IKJENDP macro instruction ends the PCL CSECT. 

4. The IKJRLSA macro instruction releases the storage obtained by the 
Parse service routine for the PDL. 
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IKJPARM - Beginning the PCL and the PPL 


Code the IKJPARM macro instruction to begin the Parameter Control List 
and to provide a symbolic address for the beginning of the Parameter 
Descriptor List returned by the Parse service routine. The PCL is 
constructed in a CSECT named by the label field of the macro 
instruction; the PDL will be mapped by the DSECT named in the DSECT 
operand of the macro instruction. 

Figure 99 shows the format of the IKJPARM macro instruction. Each of 
the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


| label | IKJPARM | 

L- X _X— 

Figure 99. The IKJPARM Macro Instruction 


{ dsectnameV 
IKJPARMD / 


1 

I 

I 

.J 


label 

The name you provide is used as the name of the CSECT in which the 
PCL is constructed. 

DSECT= 

Provides a name for the DSECT created to map the Parameter 
Descriptor List. This may be any name; the default is IKJPARMD. 


THE PARAMETER CONTROL ENTRY BUILT BY IKJPARM : The IKJPARM macro 
instruction generates the Parameter Control Entry (PCE) shown in Figure 
100. This PCE begins the Parameter Control List. 


Number of 
Bytes 

t - 

2 


Field Name 


Contents or Meaning 

Length of the Parameter Control List. This 
field contains a hexadecimal number 
representing the number of bytes in this PCL. 




Length of the Parameter Descriptor List. 

This field contains a hexadecimal number 
representing the number of bytes in the 
Parameter Descriptor List returned by the 
Parse service routine. 

---1 

This field contains a hexadecimal number 
representing the offset within the PCL to the 
first IKJKEYWD PCE or to an end-of-field 
indicator if there are no keywords. An 
end-of-field indicator may be an IKJSUBF or 
an IKJENDP PCE. 


Figure 100. The Parameter Control Entry Built by IKJPARM 
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IKJPOSIT - Describing a Delimiter-Dependent Positional Parameter 


I Code the IKJPOSIT macro instruction to describe delimiter-dependent 
positional parameters. 

The order in which you code the macros for positional parameters is 
the order in which the Parse service routine expects to find the 
positional parameters in the command string. 

I Figure 101 shows the format of the IKJPOSIT macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


label 


I 


IKJPOSIT 


r *SPACE \ 
*DELIMITER] 
*STRING 
*VALUE 
*ADDRESS \ 
t PSTRING / 
.USERID I 
,DSNAME 
,DSTHING 
r QSTRING 


) 


[ f LIST][ f RANGE] 


t 

.1 


[ *SQ STRING] 

* UPPERCASE ] [”* PROMPT= 1 prompt data * ] 

ASIS J [*DEFAULT=' default value 1 ] 


[* HELP=( 1 help data***help data 1 *...)] 

| [*VALIDCK=symbolic-address] 

-X-- 


Figure 101. The IKJPOSIT Macro Instruction 


label 


This name is used as the symbolic address within the PDL DSECT of 
the Parameter Descriptor Entry for the parameter described by this 
IKJPOSIT macro instruction. 


SPACE 
DELIMITER 
STRING 
VALUE 
ADDRESS 
PSTRING 
USERID 
DSNAME 
DSTHING 
QSTRING 

S QSTRING 

The command operand is processed either as a string or as a quoted 
string. If the delimiter is an apostrophe, the command operand is 
processed as a quoted string. If the delimiter is any of the other 
acceptable delimiter characters* the command operand is processed 
as a string. The SQSTRING option can only be specified if STRING 
is specified for the parameter type. As an example* if SQSTRING is 
coded in the IKJPOSIT macro instruction* a terminal user entering a 
command could specify either 

/string/string... or f string 1 *string* ... 

| for this positional parameter. 


These are the positional parameter types 
recognized by the Parse service routine. 

A syntactic definition of each is contained 
under the heading* "Delimiter-Dependent 
Parameters". 
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LIST 

The command operands may be entered by the terminal user as a list, 
that is, in the form: 

Command Name, (parameter,parameter, •..) 

This list option may be used with the following delimiter-dependent 
positional parameter s: 

USERID, DSNAME, DSTHING, ADDRESS, and VALUE. 


RANGE 

The command operands may be entered by the terminal user as a 
range, that is, in the form: 

Command Name parameter parameter 

This range option may be used with the following 
delimiter-dependent positional parameters: 

ADDRESS and VALUE. 

Note : The following options (UPPERCASE, ASIS, PROMPT, DEFAULT, 

HELP, and VALIDCK) may be used with all delimiter-dependent 
positional parameters except SPACE and DELIMITER. 

UPPERCASE 

The parameter is to be translated to uppercase. 


ASIS 

The parameter is to be left as it was entered by the terminal user. 
PROMPT= l prompt data' 

The parameter described by this IKJPOSIT macro instruction is 

required; the prompting data is the message to be issued if the 

parameter is not entered by the terminal user. If prompting is 
necessary and the terminal is in prompt mode. Parse adds a 
message-identifying number (message ID) and the word "ENTER” to the 
beginning of this message before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode. 
Parse adds a message ID and the word "MISSING" to the beginning of 
this message before writing it to the terminal. 

DEFAULT='default value* 

The parameter described by this IKJPOSIT macro instruction is 

required, but the terminal user need not enter it. If the 

parameter is not entered, the value specified as the default value 
is used. 

Note : If neither PROMPT nor DEFAULT is specified, the parameter is 

optional. The Parse service routine takes no action if the 
parameter specified by this IKJPOSIT macro instruction is not 
present in the command buffer. 

HELP=('help data , , , help data*...) 

You can provide up to 255 second-level messages. Enclose each 
message in apostrophes and separate the messages by single commas. 
These messages are issued one at a time after each question mark 
entered by the terminal user in response to a prompting message 
from the Parse service routine. These messages are not sent to the 
user when the prompt is for a password on a DSNAME or USERID 
parameter. 

Parse adds a message ID and the word "ENTER" (in prompt mode) or 
"MISSING" (in no-prompt mode) to the beginning of each message 
before writing it to the terminal. 
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{ VALIDCK=symbo!ic-address 

Supply the symbolic address of a validity checking subroutine if 
you want to perform additional validity checking on this parameter. 
Parse calls this routine after first determining that the parameter 
is syntactically correct. 

THE PARAMETER CONTROL ENTRY BUILT BY IKJPOSIT : The IKJPOSIT macro 
instruction generates the variable length Parameter Control Entry (PCE) 
shown in Figure 102. 


r -+ 

Number of 
Bytes 


Field 


Contents or Meaning 

--- 1 

Flags. These flags are set to indicate which 
options were coded in the IKJPOSIT macro 
instruction. 


This is an IKJPOSIT PCE. 
I PROMPT 
* DEFAULT 
Reserved 
HELP 
VALIDCK 


LIST 
AS IS 
RANGE 
SQSTRING 
Reserved 


Byte 1 
001 . 

;;= 1 s ._ . 

.... 1 ... 
.... . 0 .. 
.... .. 1 . 
.... ...1 

Byte 2 

1. mm .... 
. 1 .. .... 

.... 1 . . . 

...0 .000 


Length of the Parameter Control Entry. This 
field contains a hexadecimal number 
representing the number of bytes in this 
IKJPOSIT PCE. 




It— 


Contains a hexadecimal offset from the 
beginning of the Parameter Descriptor List to 
the related Parameter Descriptor Entry built 
by the PARSE service routine. 


1 


HEX 

1 

2 

3 

4 

5 

6 

7 

8 
9 
A 

B to 


FF 


This field contains a hexadecimal number 
indicating the type of positional parameter 
described by this PCE. These numbers have 
the following meaning: 


DELIMITER 

STRING 

VALUE 

ADDRESS 

PSTRING 

USERID 

DSNAME 

DSTHING 

QSTRING 

SPACE 

Not used. 


Figure 102. The Parameter Control Entry Built by IKJPOSIT (Part 1 of 2) 


226 Guide to Writing a TMP or a CP (Release 21.6) 










Number of 
Bytes 

l- 

1 


VARIABLE 


Field 


Contents or Meaning 


This field contains the prompting or default 
information supplied on the IKJPOSIT macro 
instruction. 

+— 


This field contains a hexadecimal number 
representing the number of second-level 
messages specified by HELP on this IKJPOSIT 
PCE. 


Contains the length minus one of the default 
or prompting information supplied on the 
IKJPOSIT macro instruction. This field and 
the next are present only if DEFAULT or 
PROMPT were specified on the IKJPOSIT macro 
instruction. 


-H 


This field contains a hexadecimal figure 
representing the length in bytes of all the 
PCE fields used for second-level messages. 

The figure includes the length of this field. 
The fields are present only if HELP is 
specified on the IKJPOSIT macro instruction. 


-H 


-H 


This field contains a hexadecimal number 
representing the length of this HELP segment. 
The length figure includes the length of this 
field, the message segment offset field, and 
the length of the information. These fields 
are repeated for each second-level message 
specified by HELP on the IKJPOSIT macro 
instruction. 


This field contains the message segment 
offset. It is set to X'OOOO*. 






Variable 


This field contains one second-level message 
supplied on the IKJPOSIT macro instruction 
specified by HELP. This field and the two 
preceding ones are repeated for each 
second-level message supplied on the IKJPOSIT 
macro instruction. These fields do not 
appear if second-level message data was not 
supplied. 


-H 


The address of a validity checking routine. 
This field is present only if a validity 
checking address was included in the IKJPOSIT 
macro instruction, 
r-x-j 

The Parameter Control Entry Built by IKJPOSIT (Part 2 of 2) 


Figure 102. 
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IKJTERM - Describing a Delimiter-Dependent Positional Parameter 


Code the IKJTERM macro instruction to describe a positional parameter 
that is one of the followings 


Statement Number 

Constant 

Variable 

Constant or Variable 

The order in which you code the macros for positional parameters is 
the order in which the Parse service routine expects to find the 
parameters in the command string. 

Figure 103 shows the format of the IKJTERM macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


j label j IKJTERM J •parameter-type•E,LIST!E # RANGE! 


,TYPE= ^ 

• 

STMT 



ICNST 


i 

VAR 1 



ANY 



UPPERCASE” 
, ASIS 


[,SBSCRPT[=label-PCE!l [,PROMPT =• prompt data 

.DEFAULTS*default valu 


i] r,i 

,1 


lue'J 


[,HELP=( 1 help data 1 ,•help data•,...)] 


| [,VALIDCK=symbolic-address![,RSVWD=label-PCE] 
-X-,- 


Figure 103. The IKJTERM Macro Instruction 


label 

This name is used as the symbolic address within the PDL DSECT of 
the Parameter Descriptor Entry for the parameter described by this 
IKJTERM macro instruction. 


Note ; The label is not used when the IKJTERM macro instruction is 
describing a subscript of a data-name. 

• parameter-type 1 

This field is required so that the parameter can be identified when 
an error message is necessary. This field differs from the PROMPT 
field in that the PROMPT field is not required and if supplied is 
used only for a required parameter that is not entered by the 
terminal user. Blanks within the apostrophes are allowed. 


LIST 

The command operands may be entered by the terminal user as a list, 
in the form: 

Command Name (parameter ,parameter,. •. ) 

The LIST option may be used with any of the TYPE= positional 
parameters. 


RANGE 

The command operands may be entered by the terminal user as a 
range, in the form: 

Command Name parameter:parameter 
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The range option may be used with any of the TYPE= positional 
parameters. 


Note : The LIST and RANGE options can not be used when the IKJTERM 

macro instruction is describing a subscript of a data-name. 

UPPERCASE 

The parameter is to be translated to uppercase. 

ASIS 

The parameter is to be left as it was entered by the terminal user. 


TYPE= 

Describes the type of the parameter as one of: 

• STMT Statement Number 

• CNST Constant 

• VAR Variable 

• Any Constant or Variable 

Note : A syntactical definition of these parameters is contained 

under the heading "Delimiter-Dependent Parameters". 

SBSCRPT[=label-PCE] 

Specifies one of two conditions: 

1. If SBSCRPT is entered with a label-PCE then the data-name 
described by the IKJTERM macro may be subscripted. Supply 
the name of the label of an IKJTERM macro instruction that 
describes the subscript. Only TYPE=VAR or TYPE=ANY 
parameters can be subscripted. 

2. If SBSCRPT is entered without a label-PCE then the IKJTERM 
macro is describing the subscript of a data-name. All 
TYPE= parameters may be used on a subscript except 
TYPE=STMT. The LIST and RANGE options can not be used on 
an IKJTERM macro that is describing a subscript. 

Note : Two IKJTERM macros are coded to describe a subscripted 

data-name. The first IKJTERM macro describes the data-name and 
specifies the SBSCRPT option with the label of the second IKJTERM 
macro. The second IKJTERM macro describes the subscript of the 
data-name and specifies SBSCRPT without a label-PCE. The second 
macro must immediately follow the first. 

PROMPT=*prompt data' 

The parameter described by this IKJTERM macro instruction is 
required. The prompting data is the message to be issued if the 
parameter is not entered by the terminal user. If prompting is 
necessary and the terminal is in prompt mode, Parse adds a 
message-identifying number (message ID) and the word "ENTER" to the 
beginning of the message before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode. 
Parse adds a message ID and the word "MISSING" to the beginning of 
the message before writing it to the terminal. If a subscripted 
data-name requires prompting, the terminal user is prompted for the 
entire name including the subscript. 

DEFAULT=*default value* 

The parameter described by this IKJTERM macro instruction is 
required, but the terminal user need not enter it. If the 
parameter is not entered, the value specified as the default value 
is used. 

. 

Note : If neither PROMPT nor DEFAULT is specified, the parameter is 

optional. The Parse service routine takes no action if the 
parameter is not present. 


Command Scan and Parse - Determining the Validity of Commands 229 



HELP=("help data f f f help data f f ...) 

You can provide up to 255 second-level messages. Enclose each 
message in apostrophes and separate the messages by single commas. 
These messages are issued one at a time after each question mark 
entered by the terminal user in response to a prompting message 
from the Parse routine. 

Parse adds a message ID and the word "ENTER" (in prompt mode) or 
"MISSING" (in no-prompt mode) to the beginning of each message 
before writing it to the terminal. 

VALI DCK=s y mb oli c-a dd r e s s 

Supply the symbolic address of a validity checking subroutine if 
you want to perform additional checking on this parameter. Parse 
calls this routine after first determining that the parameter is 
syntactically correct. 

RSVWD=labe1-PCE 

This parameter is used when TYPE=CNST or TYPE=ANY is specified. 

This option indicates that this parameter can be a figurative 
constant. Supply the address of the PCE (label on a IKJRSVWD macro 
instruction) that begins the list of reserved words that can be 
entered as a figurative constant. 

This list of reserved words is defined by a series of IKJNAME 
macros that contain all possible names and immediately follow the 
IKJRSVWD macro. 

Note : The IKJRSVWD macro can be coded anywhere in the list of 

macros that build the POL except following an IKJSUBF macro 
instruction. This permits other IKJTERM macro instructions to 
refer to the same list. 

THE PARAMETER CONTROL ENTRY BUILT BY IKJTERM s The IKJTERM macro 
instruction generates the variable Parameter Control Entry (PCE) shown 
in Figure 104. 


r- t 

| Number of | 

| Bytes | 


Field 


Byte 
110 . . 
...1 . 


Byte 

1 ... . 
. 1 .. . 
.. 1 . . 
...1 , 


Contents or Meaning 


Flags. These flags are set to indicate 
options on the IKJTERM macro instruction. 

This is an IKJTERM PCE. 

PROMPT 

DEFAULT 

Reserved 

HELP 

VALIDCK 

LIST 

ASIS 

RANGE 

This term may be SUBSCRIPTED. 

A reserved word PCE is chained from this 
term. 

Reserved 


The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the 
beginning of the Parameter Descriptor List to 
the Parameter Descriptor Entry built by the 
Parse routine. 


Figure 104. The Parameter Control Entry Built by IKJTERM (Part 1 of 2) 


230 Guide to Writing a TMP or a CP (Release 21.6) 










Number of 
Bytes 


Field 


Contents or Meaning 


1 ••• ■• • • • 

• la • 

• • 1 « • • • • 
• ••1 . * . . 
.... 1 . . • 

. 000 


This field indicates the type of positional 
parameter described by this PCE. 

STATEMENT NUMBER 

VARIABLE 

CONSTANT 

ANY (Constant or Variable) 

This term is a SUBSCRIPT term. 

Reserved 


Byte 1-2 
Byte 3-4 


Contains the hexadecimal length of the 
parameter-type field. 

Contains the offset of the parameter-type 
field. It is set to X , 0012 t . 


Variable 


Contains the parameter-type field. 


Contains the length of the default or 
prompting information supplied on the macro 
instruction. 


Variable 


Contains the default or prompting information 
supplied on the macro instruction. 


If a subscript is specified on the macro, 
this field contains the offset into the 
Parameter Control List of the subscript PCE. 


If a reserved word PCE is specified on the 
macro, this field contains the offset into 
the Parameter Control List of the reserved 
word PCE. 


Contains the length (including this field) of 
all the PCE fields used for second-level 
messages if HELP is specified on the macro. 


The number of second-level messages specified 
on the macro instruction by the HELP 
parameter. 


Contains the length of this segment including 
this field, the message offset field and 
second-level message. 

Note : This field and the following two are 

repeated for each second-level message 
specified by HELP on the macro. 


This field contains the message segment 
offset. 


Variable 


This field contains one second-level message 
specified by HELP on the macro instruction. 
This field and the two preceding fields are 
repeated for each second-level message 
specified. 


Contains the address of the validity checking 
routine if it is specified on the macro with 
the VALIDCK keyword. 


Figure 104. The Parameter Control Entry Built by IKJTERM (Part 2 of 2) 
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IKJQPER - Describing a Delimiter-Dependent Positional Parameter 

Code the IKJOPER macro instruction to provide a Parameter Control Entry 
(PCE) that describes an expression. An expression consists of three 
parts; two operands and one operator in the form: 

(operandl operator operand2) 

such ass (ABC eq 123) 

The parts of an expression are described by PCEs that are chained to 
the IKJOPER PCE. The IKJTERM macro instruction is used to identify the 
operands, and the IKJRSVWD macro instruction is used to identify the 
operator. 


Figure 105 shows the format of the IKJOPER macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


JLJtWUJt'JSK 


: parameter-t:ype ; j ,PkuMpt= : prompt data 5 j 
|_,DEFAULT= 9 default value'J 


[,HELP= ( 9 help data 1 help data 1 ,...)] 

[ f VALIDCK=symbolic-address],OPERNDl=labell 
,OPERND2=label2,RSVWD=1abel3 
[,CHAIN=label4] 


Figure 105. The IKJOPER Macro Instruction 


label 

This name is used as the symbolic address within the PDL DSECT of 
the Parameter Descriptor Entry for the parameter described by this 
IKJOPER macro instruction. 


* parameter-type 9 

This field is required so that the parameter can be identified when 
an error message is necessary. This field differs from the PROMPT 
field in that the PROMPT field is not required and if supplied is 
used only for a required parameter that is not entered by the 
terminal user. Blanks within the apostrophes are allowed. 

Note : This field is used only with error messages for the complete 

expression. The IKJTERM and IKJRSVWD PCEs are used with an error 
message for missing operands or operator. If a validity check 
routine specifies an invalid expression, then the entire expression 
is prompted for. 

PROMPT- B prompt data 9 

The parameter described by this IKJOPER macro instruction is 
required. The prompting data is the message to be issued if the 
parameter is not entered by the terminal user. If prompting is 
necessary and the terminal is in prompt mode. Parse adds a 
message-identifying number (message ID) and the word "ENTER" to the 
beginning of the message before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode. 
Parse adds a message ID and the word "MISSING" to the beginning of 
the message before writing it to the terminal. 
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DEFAULT=•default value 1 

The parameter described by this IKJOPER macro instruction is 
required f but the terminal user need not enter it. If the 
parameter is not entered the value specified as the default value 
is used. 

Note : If neither PROMPT nor DEFAULT is specified, the parameter is 

optional. The Parse service routine takes no action if the 
parameter is not present. 

HELP=('help data*, f help data - ,...) 

You can provide up to 255 second-level messages. Enclose each 
message in apostrophes and separate the messages by single commas. 
These messages are issued one at a time after each question mark 
entered by the terminal user in response to a prompting message 
from the Parse routine. 

Parse adds a message ID and the word "ENTER" (in prompt mode) or 
"MISSING" (in no-prompt mode) to the beginning of each message 
before writing it to the terminal. 

VALIDCK=symbolic-address 

Supply the symbolic address of a validity checking subroutine if 
you want to perform additional checking on this expression. Parse 
calls this routine after first determining that the expression is 
syntactically correct. 

OPERNDl=labell 

Supply the name of the label field of the IKJTERM macro instruction 
that is used to describle the first operand in the expression. 

This IKJTERM macro instruction should be coded immediately 
following the IKJOPER macro instruction that describes the 
expression. 

OPERND2=label2 

Supply the name of the label field of the IKJTERM macro instruction 
that is used to describe the second operand in the expression. 

This IKJTERM macro instruction should be coded immediately 
following the IKJNAME macro instructions that describe the operator 
in the expression under the associated IKJRSVWD macro instruction. 

RSVWD=labe13 

Supply the name of the label field of the IKJRSVWD macro 
instruction that begins the list of reserved words that are used to 
describe the possible operators to be entered for the expression. 
The IKJRSVWD and associated IKJNAME macro instructions should be 
coded immediately following the IKJTERM macro that describes the 
first operand, and immediately preceding the IKJTERM macro that 
describes the second operand. 

CHAIN=labe14 

Indicates that this parameter described by the IKJOPER macro 
instruction may be entered as an expression or as a variable. 

Supply the name of the label field of an IKJTERM macro instruction 
that describes the variable term. The LIST and RANGE options are 
not permitted on this IKJTERM macro instruction. Code this IKJTERM 
macro instruction immediately following the IKJTERM macro that 
describes the second operand. 

Note ; The Parse routine first determines if the parameter is 
entered as an expression. If the parameter is an expression, that 
is, enclosed in parentheses, then it is processed as an expression. 
If it is not an expression, then it is processed using the chained 
IKJTERM PCE to control the scan of the parameter. 
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THE PARAMETER CONTROL ENTRY BUILT BY IKJOPER s The IKJOPER macro 
instruction generates the variable Parameter Control Entry (PCE) shown 
in Figure 106. 


r - T 

| Number of | 

| Bytes | 


Field 


Contents or Meaning 


Byte 1 

111 . .... 


Byte 2 
0000 0000 


Flags. These flags are set to indicate 
options on the IKJOPER macro instruction. 


This is an IKJOPER PCE. 

PROMPT 

DEFAULT 

Reserved 

HELP 

VALIDCK 


Reserved 


The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the 
beginning of the Parameter Descriptor List to 
the Parameter Descriptor Entry built by the 
Parse routine. 


Byte 1-2 
Byte 3-4 


Contains the hexadecimal length of the 
parameter-type field. 

Contains the offset of the parameter-type 
field (X* 0012 1 )• 


Variable 


Contains the parameter-type field. 


If a reserved word PCE is specified on the 
macro, this field contains the offset into 
the Parameter Control List of the reserved 
word PCE. 


Contains the offset into the Parameter 
Control List of the OPERND1 PCE. 


Contains the offset into the Parameter 
Control List of the OPERND2 PCE. 


Contains the offset into the Parameter 
Control List of the chained term PCE if 
present. Zero if not present. 


Contains the length of the default or 
prompting information supplied on the macro 
instruction. 


Variable 


Contains the default or prompting information 
supplied on the macro instruction. 


Contains the length (including this field) of 
all the PCE fields used for second-level 
messages if HELP is specified on the macro. 


Figure 106. The Parameter Control Entry Built by IKJOPER (Part 1 of 2) 
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Number of 
Bytes 

. i 

Field 

L 

1 

Contents or Meaning | 

1 


r - —1 

The number of second-level messages specified| 
on the macro instruction by the HELP= j 
parameter. j 

2 

. . ___ ..... 

— 

. 

Contains the length of this segment including! 
this field, the message offset field and j 
second-level message. j 

1 

Note: This field and the followinq two are \ 
repeated for each second-level message | 
specified by HELP on the macro. j 

2 

L 


This field contains the message segment j 

offset. j 

|_ __ , . , | 

Variable 

.. ._ ._ 


This field contains one second-level message j 
specified by HELP on the macro instruction. | 
This field and the two preceding fields are | 
repeated for each second-level message j 
specified. j 

L ... . ... _ . _ .. . ... .. I 

3 

L J 

J 

r ~ - --““ - 1 

Contains the address of the validity checking! 
routine if it is specified on the macro with | 
the VALIDCK keyword. | 

L J 


Figure 106. The Parameter Control Entry Built by IKJOPER (Part 2 of 2) 
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Code the IKJRSVWD macro instruction with at least the 1 parameter-type' 
operand when you use it: 


• With the RSVWD keyword of the IKJOPER macro instruction to define 
the beginning of a list of the possible reserved words that can be 
an operator in an expression. The possible reserved words that can 
be operators in an expression are identified by a list of IKJNAME 
macro instructions that immediately follow the IKJRSVWD macro 
instruction. 

• By itself to define a positional reserved word. 

Code the IKJRSVWD macro instruction without operands when you use it: 

• With the RSVWD keyword of the IKJTERM macro instruction to define 
the beginning of a list of possible reserved words that can be used 
as a figurative constant. The possible figurative constants are 
defined by a list of IKJNAME macros that immediately follow the 
IKJRSVWD macro instruction. 

In this case, simply code the IKJRSVWD macro instruction as: 

I-T-T- 

| label I IKJRSVWD j 

L-X-X_ 

The order in which you code the macros for positional parameters is 
the order in which the Parse service routine expects to find the 
parameters in the command string. 

Figure 107 shows the format of the IKJRSVWD macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 

r- T - T - - —i 

| label j IKJRSVWD | 1 parameter-type• PROMPT^prompt data* | | 

j | | LDEFAULT= , default value f j 

III L J I 

| | | [ # HELP=( 1 help data 1 f *help data*,...)] | 

L-X-X_J 

Figure 107. The IKJRSVWD Macro Instruction 
label 

This name is used as the symbolic address within the PDL DSECT of 
the Parameter Descriptor Entry for the parameter described by this 
IKJRSVWD macro instruction. 

Note : The following operands are not coded on the IKJRSVWD macro 

when you use it with the RSVWD keyword of the IKJTERM macro 
instruction. 

■ parameter-type* 

This field is required so that the parameter can be identified when 
an error message is necessary. This field differs from the PROMPT 
field in that the PROMPT field is not required and if supplied is 
used only for a required parameter that is not entered by the 
terminal user. Blanks within the apostrophes are allowed. 

PROMPT= f prompt data* 

The parameter described by this IKJRSVWD macro instruction is 
required. The prompting data is the message to be issued if the 
parameter is not entered by the terminal user. If prompting is 
necessary and the terminal is in prompt mode, Parse adds a 
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message-identifying number (message ID) and the word "ENTER" to the 
beginning of the message before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode. 
Parse adds a message ID and the word "MISSING" to the beginning of 
the message before writing it to the terminal. 

DEFAULT=*default value* 

The parameter described by this IKJRSVWD macro instruction is 
required, but the terminal user need not enter it. If the 
parameter is not entered, the value specified as the default value 
is used. 

Note: If neither PROMPT nor DEFAULT is specified, the parameter is 

optional. The Parse service routine takes no action if the 
parameter is not present. 

HELP=(*help data*,*help data*,...) 

You can provide up to 255 second-level messages. Enclose each 
message in apostrophes and separate the messages by single commas. 
These messages are issued one at a time after each question mark 
entered by the terminal user in response to a prompting message 
from the Parse routine. 

Parse adds a message ID and the word "ENTER" (in prompt mode) or 
"MISSING" (in no-prompt mode) to the beginning of each message 
before writing it to the terminal. 

THE PARAMETER CONTROL ENTRY BUILT BY IKJRSVWD : The IKJRSVWD macro 
instruction generates the variable Parameter Control Entry (PCE) shown 
in Figure 108. 


Figure 108. The Parameter Control Entry Built by IKJRSVWD (Part 1 of 2) 


Number of | 
By t es | 


| Field 


Contents or Meaning 


Byte 1 

101 . ... 


Byte 2 

1 • •. .... 

0 . 

.000 0000 


Flags. These flags are set to indicate 
options on the IKJRSVWD macro instruction. 


This is an IKJRSVWD PCE. 

PROMPT 

DEFAULT 

Reserved 

HELP 

Reserved 


This PCE is used with the IKJTERM macro as a 
figurative constant. 

This PCE is not used with the IKJTERM macro 
as a figurative constant. 

Reserved 


The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the 
beginning of the Parameter Descriptor List to 
the Parameter Descriptor Entry built by the 
Parse routine. 

--- 1 


Note : The following fields are omitted if this PCE is used with the 

IKJTERM macro to describe a figurative constant. 
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Number of 
Bytes 


Field 


Contents or Meaning 


Byte 1-2 
Byte 3-4 


Contains the hexadecimal length of the 
paramet er-type field. 

Contains the offset of the parameter-type 
field (X 1 0012’)• 


Variable 


Contains the parameter-type field. 


Contains the length of the default or 
prompting information supplied on the macro 
instruction. 


Variable 


Contains the default or prompting information 
supplied on the macro instruction. 


Contains the length (including this field) of 
all the PCE fields used for second-level 
messages if HELP is specified on the macro. 


The number of second-level messages specified 
on the macro instruction by the HELP= 
parameter. 


Contains the length of this segment including 
this field, the message offset field and 
second-level message. 

Note : This field and the following two are 

repeated for each second-level message 
specified by HELP on the macro. 


This field contains the message segment 
offset. 


Variable 


This field contains one second-level message 
specified by HELP on the macro instruction. 
This field and the two preceding fields are 
repeated for each second-level message 
specified. 


Figure 108. The Parameter Control Entry Built by IKJRSVWD (Part 2 of 2) 
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IKJIDENT - Describing a Non-Delimiter Dependent Positional Parameter 


Execute the IKJIDENT macro instruction to describe a positional 
parameter that does not depend upon a particular delimiter for its 
syntactical definition — those parameters discussed under the heading 
"Positional Parameters Not Dependent on Delimiters." 

These positioned parameters must be in the form of a character 
string, with restrictions on the beginning character, additional 
characters, and length. 

The order in which you code the macro instructions for positional 
parameters is the order in which the Parse service routine expects to 
find the positional parameters in the command string. 

Figure 109 shows the format of the IKJIDENT macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


label j IKJIDENT | *parameter-type' [,LIST][,RANGE][,PTBYPS] 

[, ASTERISK] T,UPPERCASE*] [ ,MAXLNTH= number] 
|,ASIS J 



ALPHA 1 




[alpha 


,FIRST= 

NUMERIC 



,OTHER= 

iNUMERIC 



Ialphanum 1 




Ialphanum 1 



(ANY 




any 



NONATABC 




[NONATABC 



[nonatnumj 




k NONATNUM 



[: 


PROMPT = 1 prompt data 
DEFAULT= f default value 


lue B J 


l -x-x- 


[VALIDCK=symbolic-address] 

[,HELP =( 1 help dat a 1 ,•help data *, 


,)] 


L-X 

Figure 109. The IKJIDENT Macro Instruction 


_j 


label 

This name is used within the PDL DSECT as the symbolic address of 
the Parameter Descriptor Entry for this positional parameter. 

1 parameter-type 1 

This field is required so that the parameter can be identified when 
an error message is necessary. This field differs from the PROMPT 
field in that the PROMPT field is not required and if supplied is 
used only for a required parameter that is not entered by the 
terminal user. Blanks within the apostrophes are allowed. 


LIST 

This positional parameter may be entered by the terminal user as a 
list, that is, in the form: 

Command Name (parameter,parameter,...) 

RANGE 

This positional parameter may be entered by the terminal user as a 
range, that is, in the form: 

Command Name parameter:parameter 

PTBYPS 

All prompting for the parameter is to be done in print inhibit 
mode. This option may be specified only when the PROMPT option is 
specified. 
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ASTERISK 

An asterisk may be substituted for this positional parameter. 
UPPERCASE 

The parameter is to be translated to uppercase. 


ASIS 

The parameter is to be left as it was entered. 

MAXLNTH=number 

The maximum number of characters the string may contain. If you do 
not code the MAXLNTH operand, the Parse service routine accepts a 
character string of any length. 

FIRST= 

Specify the character type restriction on the first character of 
the string. 

OTHER= 

Specify the character type restriction on the characters of the 
string other than the first character. 

Note ; The restrictions on the characters of the string are 
specified by coding one of the following character types after the 
FIRST= and the OTHER= operands: 

ALPHA 

An alphabetic or national character. ALPHA is the default 
value for both the FIRST and the OTHER operands. 

NUMERIC 

A digit, 0-9. 

ALPHANUM 

An alphabetic, numeric, or national character. 

ANY 

Any character other than a blank, comma, tab, or semicolon. 
Parentheses must be balanced. 

NONATABC 

An alphabetic character only. National characters and 
numerics are excluded. 

NONATNUM 

An alphabetic or numeric character. National characters are 
excluded. 

PROMPT=*prompt data* 

The parameter is required; the prompting data is the message to be 
issued if the parameter is not entered by the terminal user. If 
prompting is necessary and the terminal is in prompt mode. Parse 
adds a message-identifying number (message ID) and the word "ENTER” 
to the beginning of this message before writing it to the terminal. 

If prompting is necessary but the terminal is in no-prompt mode. 
Parse adds a message ID and the word "MISSING" to the beginning of 
this message before writing it to the terminal. 

DEFAULT=»default value* 

The parameter is required, but a default value may be used. If the 
parameter is not entered by the terminal user, the value specified 
as the default value is used. 

Note : The parameter is optional if neither PROMPT nor DEFAULT is 

specified. The Parse service routine takes no action if the 
parameter specified by this IKJIDENT macro instruction is not 
present in the command buffer. 


240 
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VALIDCK=symbol ic- address 

Supply the symbolic address of a validity checking subroutine if 
you want to perform additional validity checking on this parameter. 
The Parse service routine calls the addressed routine after first 
determining that the parameter is syntactically correct. 

HELP=(* help data B ,■help data' ...) 

You can provide up to 255 second-level messages. Enclose each 
message in apostrophes and separate the messages by single commas. 
These messages are issued one at a time after each question mark 
entered by the terminal user in response to a prompting message 
from the Parse service routine. These messages are not sent to the 
user when the prompt is for a password on a DSNAME or USERID 
parameter. 

Parse adds a message ID and the word "ENTER" (in prompt mode) or 
"MISSING" (in no-prompt mode) to the beginning of each message 
before writing it to the terminal. 


THE PARAMETER CONTROL ENTRY BUILT BY IKJIDENT : The IKJIDENT macro 
instruction generates the variable length Parameter Control Entry (PCE) 
shown in Figure 110. 


r-T 

Number of 
Bytes 


Field 


Contents or Meaning 

--j 

Flags. These flags are set to indicate which 

options were coded in the IKJIDENT macro 
instruction. 


Byte 1 
100 . .... 
1 .... 
. 1 ... 
. . 0 .. 
. .. 1 . 
. ... 1 

Byte 2 

. 1 .. .... 

...0 0000 


This is an IKJIDENT PCE. 

PROMPT 

DEFAULT 

Reserved 

HELP 

VALIDCK 


LIST 
AS IS 
RANGE 
Reserved 


— | 


Length of the Parameter Control Entry, 
field contains a hexadecimal number 
representing the number of bytes in this 
IKJIDENT PCE. 


This 


-1 

Contains a hexadecimal offset from the 
beginning of the Parameter Descriptor List to 
the related Parameter Descriptor Entry built 
by the PARSE service routine. 


-H 

A flag field indicating the options coded on 
the IKJIDENT macro instruction. 

ASTERISK 
MAXLNTH 
PTBYPS 
Reserved 

L_X_X_J 

Figure 110. The Parameter Control Entry Built by IKJIDENT (Part 1 of 3) 


1. 

. 1 .. .... 

...0 0000 
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1 T 1 

| Number of | 

| Bytes | Field 

i i 

r i 

Contents or Meaning j 

r t 

I 1 1 

1 1 

1 1 

1 1 

| | HEX 

1 1 o 

1 1 1 

I 1 2 

1 1 3 

1 1 4 

1 1 5 

| | 6 to FF 

i l 

r — 1 
This field contains a hexadecimal number | 
indicating the character type restriction on j 
the first character of the character string j 
described by the IKJIDENT macro instruction. | 
Acceptable Characters: I 

Any (except blank, comma, tab, semicolon). j 
Alphabetic or national. j 
Numeric. j 
Alphabetic, national, or numeric. j 
Alphabetic. j 
Alphabetic or numeric. j 
Not used. j 

_ . _ l 

r t 1 

1 1 1 

1 1 

1 i 

1 1 

| I HEX 

This field contains a hexadecimal number | 
indicating the character type restriction on | 
the other characters of the character string j 
described by the IKJIDENT macro instruction, j 
Acceptable Characters: 

1 1 0 

1 1 1 

1 1 2 

1 1 3 

1 1 4 

1 1 5 

| | 6 to FF 

L 1 1 

Any (except blank, comma, tab, semicolon). 
Alphabetic or national. 

Numeric. 

Alphabetic, national, or numeric. 

Alphabetic. 

Alphabetic or numeric. 

Not used. 

L.... . .. . ... ... . 

I. t ■■ —. 

| 2 | 

1 1 

i 1 

l 1 

l 1 

1 1 

1 1 

This field contains a hexadecimal number 
representing the length of the parameter type 
segment. This figure includes the length of 
this field, the length of the message segment 
offset field, and the length of the Parameter 
type field supplied on the IKJIDENT macro 
instruction. 

_.. . .. .. ... ...... ..... ....... 

r. ^ 1 

1 2 | 

1 1 

1 4 

This field contains the message segment 
offset. It is set to X'0012'. 

1 1 

j Variable | 

i i 

i i 

4 4- _ _ 

This field contains the field supplied as the 
parameter type operand of the IKJIDENT macro 
instruction. 

r- T - 

1 1 1 
l i 

i i 

i i 

i i 

1 1 

This field contains a hexadecimal number 
representing the mexaimum number of 
characters the string may contain. This 
field is present only if the MAXLNTH operand 
was coded on the IKJIDENT macro instruction. 

i + i 

i i i 

i i 

i i 

i i 

i i 

i i 

L 1 . . 

This field contains the length minus one of 
the default or prompting information supplied 
on the IKJIDENT macro instruction. This 
field and the next are present only if 

DEFAULT or PROMPT were specified on the 
IKJIDENT macro instruction. 

r t 

| Variable | 

i i 

i i 

L J. J 

This field contains the prompting or default 
information supplied on the IKJIDENT macro 
instruction. 

L J 


Figure 110. The Parameter Control Entry Built by IKJIDENT (Part 2 of 3) 
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Number of 
Bytes 


Field 


| Contents or Meaning 


|This field contains a hexadecimal figure 
|representing the length in bytes of all the 
|PCE fields used for second-level messages. 

|The figure includes the length of this field. 
|The fields are present only if HELP is 
(specified on the IKJIDENT macro instruction. 


jThis field contains a hexadecimal number 
|representing the number of second-level 
jmessages specified by HELP on this IKJIDENT 
| PCE. 


|This field contains a hexadecimal number 
|representing the length of this HELP segment, 
jThe figure includes the length of this field, 
|the message segment offset field f and the 
|length of the information. These fields are 
|repeated for each second-level message 
j specified by HELP on the IKJIDENT macro 
jinstruction. 


|This field contains the message segment 
joffset. It is set to X'0000'. 


Variable 


|This field contains one second-level message 
|supplied on the IKJIDENT macro instruction 
(specified by HELP. This field and the two 
j preceding ones are repeated for each 
|second-level message supplied on the IKJIDENT 
|macro instruction; these fields do not appear 
jif no second-level message data was supplied. 


| 3 | |The address of a validity checking routine. j 

| | |This field is present only if a validity j 

| | |checking address was included in the IKJPOSIT| 

| | jmacro instruction. j 

L-X-X-J 

Figure 110. The Parameter Control Entry Built by IKJIDENT (Part 3 of 3) 
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IKJKEYWD - Describing a Keyword Parameter 

Execute the IKJKEYWD macro instruction to describe a keyword parameter. 
Execute a series of IKJNAME macro instructions to indicate the possible 
names for the keyword parameter. Keyword parameters may appear in any 
order in the command but must follow all positional parameters. A user 
is never required to enter a keyword parameter; if he does not f the 
default value you supply* if you choose to supply one, is used. 

Keywords may consist of any combination of alphameric characters up to 
31 characters in length* the first of which must be an alphabetic 
character. 

Figure 111 shows the format of the IKJKEYWD macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 

r- t-t- 

Ilabelj IKJKEYWD | [DEFAULT= 1 default-value 1 ] 

L-J-J_ 

Figure 111. The IKJKEYWD Macro Instruction 


label 

This name is used within the PDL DSECT as the symbolic address of 
the Parameter Descriptor Entry for this parameter. 

DEFAULTS default-value 1 

The default value you specify is the value that is used if this 
keyword is not present in the command buffer. Specify the valid 
keyword names with IKJNAME macro instructions following this 
IKJKEYWD macro instruction. 
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Number of 
Bytes 


Field 


Contents or Meaning 


This field contains a hexadecimal offset from 
the beginning of the Parameter Descriptor 
List to the related Parameter Descriptor 
Entry built by the PARSE service routine. 


This field contains the length minus one of 
the default information supplied on the 
IKJKEYWD macro instruction. This field and 
the next are present only if DEFAULT was 
specified on the IKJKEYWD macro instruction. 


Variable 


This field contains the default value 
supplied on the IKJKEYWD macro instruction. 


Figure 112, The Parameter Control Entry Built by IKJKEYWD (Part 2 of 2) 


IKJNAME - Listing the Keyword or Reserved Word Parameter Names 

The IKJNAME macro instruction may be coded with the following two macro 
in strue tions. 

1. With the IKJKEYWD macro instruction to define keyword parameter 
names. 

2. With the IKJRSVWD macro instruction to define reserved word 
parameter names. 

A description and format of the IKJNAME macro instruction for both 
methods of coding follows. 

1. Code a series of IKJNAME macro instructions to indicate the 
possible names for a keyword parameter. One IKJNAME macro 
instruction is needed for each possible keyword name. Code the 
IKJNAME macro instructions immediately following the IKJKEYWD macro 
instruction to which they pertain. 

Figure 113 shows the format of the IKJNAME macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 

r- T --r- 

| | IKJNAME | 'keyword-name' [ # SUBFLD=subfield-name] 

1 I I 

| | | [ # INSERT='keyword-string'] 

l _r_ jl_ 

Figure 113. The IKJNAME Macro Instruction (When used with the IKJKEYWD 
Macro Instruction) 

keyword-name 

One of the valid keyword parameters for the IKJKEYWD macro 
instruction that precedes this IKJNAME macro instruction. 

SUBFLD=subfield-name 

This option indicates that this keyword name has other parameters 
associated with it. Use the subfield-name as the label field of 
the IKJSUBF macro instruction that begins the description of the 
possible parameters in the subfield. 



Command Scan and Parse - Determining the Validity of Commands 245 












INSERT=' keyword-string' 

The use of some keyword parameters may imply that other keyword 
parameters are required. The Parse service routine inserts the 
keyword, string specified into the command string just as if it had 
been entered as part of the original command string. The command 
buffer is not altered. 

2. Code a series of IKJNAME macro instructions to indicate the 

possible names for reserved words. One IKJNAME macro instruction 
is needed for each possible reserved word name. Code the IKJNAME 
macro instructions immediately following the IKJRSVWD macro 
instruction to which they apply. 

Figure 114 shows the format of the IKJNAME macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 

r- T - T -i 

| | IKJNAME I 'reserved-word name' I 

L - JL -J. _J 

Finure 114- The IKJNAME Macro Instruction (when used with the IKJRSVWD 
macro) 

reserved-word name 

One of the valid reserved word parameters for the IKJRSVWD macro 
instruction that precedes the IKJNAME macro instructions. 

Note : The IKJNAME macro instruction has two uses when coded with 

the IKJRSVWD macro instruction. The reserved-words identified on 
the IKJNAME macros may be figurative constants when the IKJRSVWD 
macro is chained from an IKJTERM macro, or operators in an 
expression when the IKJRSVWD macro is chained from the IKJOPER 
macro. 
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THE PARAMETER CONTROL ENTRY BUILT BY IKJNAME : The IKJNAME macro 
instruction generates the variable length Parameter Control Entry (PCE) 
shown in Figure 115. 

Note : Only the first four fields are valid when the IKJNAME macro 

instruction is coded with the IKJRSVWD macro instruction. 


r t i 

Number of | 

Bytes | Field 

.. . i ...... ..... ... 

1 

Contents or Meaning | 

T 1 

2 1 

1 

1 

1 

| Byte 1 

| Oil. 

| ...0 0... 

1 .... .1.. 

| .00 

1 

| Byte 2 

| 000. 

| ...1 .... 

| .... 0000 
l 

r - - - --- 1 

Flags. These flags are set to indicate which| 

options were coded in the IKJNAME macro j 

instruction. | 

i 

i 

This is an IKJNAME PCE. j 

Reserved. j 

SUBFLD j 

Reserved. j 

1 

1 

Reserved. | 

INSERT j 

Reserved. j 

. j 

I T 1 

2 I 

1 

1 

1 

i 

i 

Length of the Parameter Control Entry. This | 
field contains a hexadecimal number j 
representing the number of bytes in this j 
IKJNAME PCE. j 

r~ t 1 

1 1 

1 

1 

i j 

| 

This field contains the length minus one of j 
the keyword or reserved word name specified | 
on the IKJNAME macro instruction* | 

1 

Variable | 

i 

i 

r - 1 

This field contains the keyword or reserved | 
word name specified on the IKJNAME macro j 
instruction. j 

r~ " t 1 

2 I 

1 

1 

1 

1 

1 

r 1 

This field contains a hexadecimal offset f | 

plus one, from the beginning of the Parameter! 
Control List to the beginning of a subfield j 
PCE. This field is present only if the j 

SUBFLD operand was specified in the IKJNAME j 

macro instruction. j 

r t 1 

1 1 

1 

1 

1 

1 

r — 1 
This field contains the length minus one of | 
the keyword string included as the INSERT | 
operand in the IKJNAME macro instruction. | 
This field and the next are not present if j 
INSERT was not specified. j 

Variable j 

i 

i 

LX J 

_ ... ..... . _ ^ 

This field contains the keyword string j 
specified as the INSERT operand of the j 
IKJNAME macro instruction. j 
L J 


Figure 115. The Parameter Control Entry Built by IKJNAME 
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IKJSUBF - Describing a Keyword Subfield 


Keyword parameters may have subfields associated with them. A subfield 
consists of a parenthesized list of parameters directly following the 
keyword. 

Execute the IKJSUBF macro instruction to indicate the beginning of a 
subfield description. The IKJSUBF macro instruction ends the main part 
of the Parameter Control List or the previous subfield description and 
begins a new subfield description. 

Note that the IKJSUBF macro instruction is used only to begin the 
subfield description; the subfield is described using the IKJPOSIT f 
IKJIDENT, and IKJKEYWD macro instructions, depending upon the type of 
parameters within the subfield. 

You must use the name you have coded as the SUBFLD operand of the 
IKJNAME macro instruction for the label of this macro instruction. 

Figure 116 shows the format of the IKJSUBF macro instruction. 

Appendix B describes the notation used to define macro instructions. 

r- t-t-----1 

| label I IKJSUBF | | 

L-X-X___ J 

Figure 116. The IKJSUBF Macro Instruction 
label 

The name you supply as the label of this macro instruction must be 
the same name you have coded as the SUBFLD operand of the IKJNAME 
macro instruction describing the keyword name that takes this 
subfield. 


THE PARAMETER CONTROL ENTRY BUILT BY IKJSUBF : The IKJSUBF macro 
instruction generates the Parameter Control Entry (PCE) shown in Figure 
117. 


i— 


Number of 
Byt es 


Field 


Contents or Meaning 


000 . .... 


...0 0000 


Flags. These flags indicate which type of 
PCE this is. 

This PCE indicates an end-of-field. These 
end-of-field indicators are present in 
IKJSUBF and IKJENDP PCEs; they indicate the 
end of a previous subfield or of the PCL 
itself. 

Reserved. 


1 


This field contains a hexadecimal number 
representing the offset within the PCL to the 
first IKJKEYWD PCE or to the next 
end-of-field indicator if there are no 
keywords in this subfield. 


Figure 117. The Parameter Control Entry Built by IKJSUBF 


248 Guide to Writing a TMP or a CP (Release 21.6) 











IKJENDP - Ending the Parameter Control List 


Execute the IKJENDP macro instruction to inform the Parse service 
routine that it has reached the end of the Parameter Control List built 
for this command. 

Figure 118 shows the format of the IKJENDP macro instruction. 
Appendix B describes the notation used to define macro instructions. 


r-T"- t- 1 

| | IKJENDP | | 

L-X_X-J 


Figure 118. The IKJENDP Macro Instruction 


THE PARAMETER CONTROL ENTRY BUILT BY IKJENDP : The IKJENDP macro 
instruction generates the Parameter Control Entry (PCE) shown in Figure 
119. It is merely an end-of-field indicator. 


r - T -T- 1 

| Number of | | | 

| Bytes | Field |Contents or Meaning | 

f-i-*1-1 

| 1 | |Flags. These flags are set to indicate | 

| | |end-of-field. | 

I | 000.jEnd-of-field indicator. Indicates the end ofj 

j | |the PCL. | 

I | ...0 0000 (Reserved. j 

L-X-X_J 

Figure 119. The Parameter Control Entry Built by IKJENDP 
IKJRLSA - Releasing Storage Allocated by Parse 


Execute the IKJRLSA macro instruction to release storage allocated by 
the Parse service routine and not previously released by Parse. This 
storage consists of the Parameter Descriptor List (PDL) returned by the 
Parse service routine and any storage obtained for new data received by 
Parse as a result of a prompt. 

If the return code from the Parse service routine is non-zero f all 
storage allocated by Parse has been freed by Parse. In that case, this 
macro instruction need not be issued, but will not cause an error if it 
is issued. 


Figure 120 shows the format of the IKJRLSA macro instruction. Each 
of the operands is explained following the figure. Appendix B describes 
the notation used to define macro instructions. 


j label j IKJRLSA | (address of the answer place) j 

I I I 1(1-12) / | 

L-X-X-J 

Figure 120. The IKJRLSA Macro Instruction 
address of the answer place 

The address of the word within the Parse Parameter List in which 
Parse placed a pointer to the PDL when control was returned to the 
command processor. This address may be loaded into one of the 
general registers 1 through 12, right adjusted with the unused high 
order bits set to zero. See the section headed "Passing Control to 
the Parse Service Routine" for a description of the Parse Parameter 
List. 


Command Scan and Parse - Determining the Validity of Commands 249 








PASSING CONTROL TO THE PARSE SERVICE ROUTINE 


You pass control to the Parse service routine by issuing a LINK macro 
instruction specifying IKJPARS as the entry point. Before you LINK to 
the Parse service routine however, you must build a Parse Parameter List 
(PPL), and place its address into register 1. This PPL must remain 
intact until Parse returns control to the calling routine. Figure 121 
shows this flow of control between a Command Processor and the Parse 
service routine. 



Figure 121. Control Flow Between Command Processor and Parse 
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The Parse Parameter List 


The Parse Parameter List (PPL) is a seven-word parameter list containing 
addresses required by the Parse service routine. 

The PPL is defined by the IKJPPL DSECT. Figure 122 shows the format 
of the Parse Parameter List. 


Number of 
Bytes 


Field 


Contents or Meaning 


PPLUPT 


The address of the User Profile Table. 


-H 


PPLECT 


The address of the Environment Control Table. 


PPLECB 


The address of the Command Processor's Event 
Control Block. The ECB is one word of 
storage, declared and initialized to zero by 
the Command Processor. 


1 


-H 


PPLPCL 


The address of the Parameter Control List 
created by the Command Processor using the 
Parse macro instructions. Use the label on 
the IKJPARM macro instruction as the symbolic 
address of the PCL. 


1 


PPL AN S 


The address of a fullword of storage, 
supplied by the calling routine, in which the 
Parse service routine places a pointer to the 
Parameter Descriptor List (PDL)• If the 
parse of the command buffer is unsuccessful. 
Parse sets the pointer to the PDL to 
FF000000. 


H 


PPLCBUF 


The address of the command buffer. 


PPLUWA 


The address of a user supplied work area. 
This field can contain anything that the 
calling routine wishes passed to a validity 
checking routine. 


Figure 122. The Parse Parameter List 
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FORMATS OF THE PDES RETURNED BY PARSE 


Parse returns the results of the scan of the command buffer to the 
command processor in a Parameter Descriptor List (PDL). The PDL, built 
by Parse, consists of Parameter Descriptor Entries (PDE) f which contain 
pointers to the parameters, indicators of the options specified, and 
pointers to the subfield parameters entered with the command operands. 

Use the IKJPARMD DSECT to map the PDL and each of the PDEs. Base the 
IKJPARMD DSECT on the PDL address returned by the Parse service routine. 
The PPLANS field of the Parse Parameter List points to a fullword of 
storage that contains the address of the PDL. Then use the labels you 
used on the Parse macro instructions to access the corresponding PDEs. 

The format of the PDE depends upon the type of parameter parsed. For 
a discussion of parameter types, see the topic "Command Parameter 
Syntax." The following description of the possible PDEs within a PDL 
shows each of the PDE formats and the type of parameters they describe. 

The PDL Header 


The PDL begins with a two word header. The DSECT= operand of the 
IKJPARM macro instruction provides a name for the DSECT created to map 
the PDL. Use this name as the symbolic address of the beginning of the 
PDL header. 


+ 0 



A pointer to the next block of storage 

-T- 

I + 6 

Subpool number j LENGTH 

_-L- 


I 

I 

A 


Pointer to the next block of storages 

The Parse service routine gets storage for the PDL and for any data 
received as the result of a prompt. Each block of storage obtained 
begins with another PDL header. The blocks of storage are forward 
chained by this field. A forward chain pointer of FF000000 in this 
field indicates that this is the last storage element obtained. 

Subpool number: 

This field will always indicate subpool 1. All storage allocated 
by the Parse service routine for the PDL and for data received from 
a prompt is allocated from subpool 1. 

Length s 

This field contains a hexadecimal number indicating the length of 
this block of storage (this PDL); the length includes the header. 

PDEs Created for Positional Parameters 


The labels you use to name the macro instructions provide access to the 
corresponding PDEs. The positional parameters described by the 
IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD and the IKJIDENT macro instructions 
have the following PDE formats. 

SPACE, DELIMITER : The Parse service routine does not build a PDE for 
either a SPACE or a DELIMITER parameter. 


252 Guide to Writing a TMP or a CP (Release 21.6) 






| STRING, PSTRING, AND QSTRING : PARSE uses the IKJPOSIT macro to build a 
two-word PDE to describe a STRING, PSTRING, or a QSTRING parameter; the 
PDE has the following format 2 


+ 0 


i 

A pointer to the character string j 

J 

+ 4 

Length 

T 

1 + 6 

1 

X 

T 

1 + 7 | 

Flags | Reserved | 

1 - j 


Pointer to the character string: 

Contains a pointer to the beginning of the character string, or a 
zero if the parameter was omitted. 

Length: 

Contains the length of the string. Any punctuation around the 
character string is not included in this length figure. 

The length is zero if the string is omitted or if the string is 
null. 

Flags 2 

0. The parameter is not present. 

1... .... The parameter is present. 

•xxx xxxx Reserved bits. 

Note : If the string is null, the pointer is set f the length is 

zero, and the flag bit is 1. 


| VALUE : Parse uses the IKJPOSIT macro to build a two word PDE to 
describe a VALUE parameter; the PDE has the following format: 


1- 1 

I +0 | 

| A pointer to the character string | 

[ - T - T -{ 

|+4 |+6 |+7 | 

| Length | Flags | Type-char. | 

L- ± _-L-J 


Pointer to the character string: 

Contains a pointer to the beginning of the character string, that 
is, the first character after the quote. Contains a zero if the 
VALUE parameter is not present. 

Length: 

Contains the length of the character string excluding the quotes. 
Flags: 

0. The parameter is not present. 

1. The parameter is present. 

.xxx xxxx Reserved bits. 

Type-character: 

Contains the letter that precedes the quoted string. 
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| DSNAME, DSTHING : Parse uses the IKJPOSIT macro to build a six-word PDE 
to describe a DSNAME or a DSTHING parameter. The PDE has the following 
format: 


r 

1 + o 

1 

A pointer 

to 

the dsname 






r - 

1 +( * 

Lengthl 


i 

i 

i 

+ 6 

Flagsl 

T“ 

i 

i 

±_ 

+7 

Reserved 

r — 

1 +8 

i_ 

A pointer 

to 

the member name 





r 

| +12 

1 

Length2 


T 

1 

1 

I 

+ 14 

Flags2 

T~ 

1 

1 

_L_ 

+15 

Reserved 

r 

| +16 

i 

A pointer 

to 

the password 






| +20 

L 

Length3 


i 

i 

i 

-L- 

+ 22 

Flags3 

- 

1 

1 

_ X. 

+23 

Reserved 


Pointer to the dsname: 

Contains a pointer to the beginning of the data set name. Contains 
zero if the data-set name was omitted. 


Lengthl: 

Contains the length of the data set name. If the data set name is 
contained in quotes, this length figure does not include the 
quotes. 


Flags1 2 

0 ... .... 
1 ... .... 
• 0 .. .... 

..XX xxxx 


The data set name is not present. 

The data set name is present. 

The data set name is not contained within quotes. 
The data set name is contained within quotes. 
Reserved bits. 


Pointer to the member name: 

Contains a pointer to the beginning of the member name. Contains 
zero if the member name was omitted. 

Length2: 

Contains the length of the member name. This length figure does 
not include the parentheses around the member name. 

Flags 2: 

0... .... The member name is not present. 

1. The member name is present. 

.xxx xxxx Reserved bits. 

Pointer to the password: 

Contains a pointer to the beginning of the password. Contains zero 
if the password was omitted. 

Length3: 

Contains the length of the password. 

Flags3: 

0. The password is not present. 

1... .... The password is present. 

.xxx xxxx Reserved bits. 
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I ADDRESS : Parse uses the IKJPOSIT macro to build a nine-word PDE to 
describe an ADDRESS parameter. The PDE has the following formats 


+0 

A pointer 

to 

the 

load name 




+4 

Lengthl 



~ T 

1 + 6 

1 

_. i 

Flagsl 

T 

1 +7 

1 

r 

Reserved 

+ 8 

A pointer 

to 

the 

entry name 




+12 

Length2 



S +14 

1 

j. _ 

Flags2 

| +15 

1 

x 

Reserved 

+16 

A pointer 

to 

the 

address string 




+20 

Length3 



j +22 

1 

Flags3 

| +23 

1 

Reserved 

■ TTT m- r... in 

+24 

--*“ ~T“ 

1 

Flags4 | 

i 

+ 25 

| 

| +26 
Sign | 

_L 

Indirect count 


+28 

A pointer 

to 

the 

first expression value 

PDE 


f - 

+32 

L 

Reserved : 

for 

use 

by user validity check 

rtn. 



Pointer to the load name: 

Contains a pointer to the beginning of the load module name. 
Contains zero if no load module name was specified. 


Lengthls 

Contains the length of the load module name, excluding the period. 


Flagsl: 

0 . 

1 ... .... 

.XXX xxxx 


The load module name is not present. 
The load module name is present. 
Reserved bits. 


Pointer to the entry names 

Contains a pointer to the name of the CSECT, zero if the CSECT name 
is not specified. 


Length2 s 

Contains the length of the entryname, excluding the period. 


Flags2: 

0 ... .... 

1 . 

.XXX xxxx 


The entry name is not present. 
The entry name is present. 
Reserved bits. 


Pointer to the address strings 

Contains a pointer to the address string portion of a qualified 
address. Contains a zero if the address string was not specified. 
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Length3: 

Contains the length of the address string portion of a qualified 
address. This length count excludes the following characters for 
the following address types: 


1. Relative address - excludes the plus sign. 

2. Register address - excludes letters. 

3. Absolute address - excludes period. 


Flags3: 

0... .... The address string is not present. 

1. The address string is present. 

.xxx xxxx Reserved bits. 

Flags4: 

The bits set in this one byte flag field indicate the type of 
address found by the Parse service routine. 


Bit Setting 
0000 0000 
1000 0000 
0100 0000 
0010 0000 
0001 0000 
0000 1000 


Hex Meaning 

00 Absolute address. 

8 0 s^rnbolic add res s - 

4 0 Rela tive address. 

20 General register. 

10 Double precision floating point register. 
08 Single precision floating point register. 


Sign: 

Contains the arithmetic sign character used before an expression 
value. Contains a zero if the address is not an address 
expression• 

Indirect count: 

Contains a number representing the number of levels of indirect 
addressing. 

Pointer to the first expression value PDE: 

If the address is in the form of an address expression, this is a 
pointer to the PDE for the first expression value. Contains 
hexadecimal FF000000 if the address is not an address expression. 

User word for validity checking routine: 

A word provided for use by the user-written validity checking 
routine. 
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EXPRESSION VALUE : If an ADDRESS parameter is found to be in the form of 
an address expression, the Parse service routine builds an expression 
value PDE for each expression value within the address expression. 

These expression value PDEs are chained together, beginning at the 
eighth word of the address PDE built by Parse to describe the address 
parameter. The last expression value PDE is indicated by hexadecimal 
FF000000 in its fourth word,, the forward chaining field. 

Parse uses the IKJPOSIT macro to build a four word PDE to describe an 
expression value, it has the following format: 


r~ 

1 +o 

A pointer to 

the 

address 

i 

1 

string | 

___ .... i 

i 

i 

Length3 


T 

1 + 6 

1 

T 

1 

Reserved | 

■ 

r 

1 +8 

| Flags5 

L 

l 

1 +9 

| Sign 

L 


J 

| +10 

1 

7 

1 

Indirect count | 

i 

r 

| +12 

A pointer to 

the 

1 

next expression value | 


L-J 


Pointer to the address string: 

Contains a pointer to the expression value address string. 

Length3: 

Contains the length of the expression value address string. The N 
is not included in this length value. 

Flags5: 

The Parse service routine sets these flags to indicate the type of 
expression value: 

Bit Setting Hex Meaning 

0000 0100 04 This is a decimal expression value. 

0000 0010 02 This is a hexadecimal expression value. 

Sign: 

Contains the arithmetic sign character used before an expression 
value. 

Indirect count: 

Contains a number representing the number of levels of indirect 
addressing within this particular address expression. 

Pointer to the next expression value PDE: 

Contains a pointer to the next expression value PDE if one is 
present; contains hexadecimal FF000000 if this is the last 
expression value PDE. 
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I USERID : Parse uses the IKJPOSIT macro to build a four-word PDE to 
describe a USERID parameter; it has the following format: 


| f + 0 

L 

A pointer 

to the userid 





r 

1 +4 

i _ 

Lengthl 


i +6 

1 

± ... 

Flagsl 

i 

1 +7 

1 

_ L . . 

Reserved 

r- 

1 +8 

A pointer 

to the password 





j. _ 

| +12 

L 

Length2 


I +14 

1 

Flags2 

| +15 

1 

J. 

Reserved 


Pointer to the userid: 

Contains a pointer to the beginning of the userid. Contains zero 
if the userid was omitted. 


Lengthl: 

Contains the length of the userid. 


Flags 1: 

0. 

1. 

.XXX xxxx 


The userid is not present. 
The userid is present. 
Reserved bits. 


Pointer to the password: 

Contains a pointer to the beginning of the password. Contains zero 
if the password is omitted. 


Length2: 

Contains the length of the password, excluding the slash. 


Flags2: 

0. 

1 ... .... 

xxxx xxxx 


The password is not present. 
The password is present. 
Reserved bits. 


CONSTANT : Parse uses the IKJERM macro to build a five word PDE to 

describe a CONSTANT parameter. The PDE has the following format: 


r- t -r- 1 

|+0 |+1 |+2 | 

| Lengthl | Length2 | Reserved j 

I*--- x -+-^ 

|+4 |+6 | 

| Reserved Word Number | Flags j 

t -x-1 

I + 8 I 

| A pointer to the string of digits | 

i -1 

j+12 | 

| A pointer to the exponent j 

lr - ^ 

I +16 | 

| A pointer to the decimal point j 

L-J 
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Lengthl 

Contains the length of term entered, depending on the type of 
parameter entered as follows: 

• For a fixed-point numeric literal, the length includes the 
digits but not the sign or decimal point. 

• For a floating-point numeric literal, the length includes the 
mantissa (string of digits preceding the letter E) but not the 
sign or decimal point. 

• For a non-numeric literal, the length includes the string of 
characters but not the apostrophes. 

Length2 

For a floating-point numeric literal, length2 contains the length 
of the string of digits following the letter E but not the sign. 

Reserved Word Number 

The reserved word number contains the number of the IKJNAME macro 
that corresponds to the entered name. 

Note : The possible names of reserved words are given by coding a 

list of IKJNAME macros following an IKJRSVWD macro. One IKJNAME 
macro is needed for each possible name. If the name entered does 
not correspond to one of the names in the IKJNAME macro list then 
this field is set to zero. 


Flags 

Byte 1 

0 .. . 
1 ... 
. 1 .. 
.. 1 . 




The parameter is missing. 

The parameter is present. 
Constant. 

Variable. 

Statement Number. 

Fixed-point numeric literal. 
Non-numeric literal. 

Figurative constant. 
Floating-point numeric literal. 


Byte 2 

1 . 

.0 . 


.1 . 


... X xxxx 


Sign on constant is either plus or omitted. 

Sign on constant is minus. 

Sign on exponent of floating-point numeric 
literal is either plus or omitted. 

Sign on exponent of floating-point numeric literal 
is munus. 

Decimal point is present. 

Reserved bits. 


Pointer to the string of digits: 

Contains a pointer to the string of digits, not including the sign 
if entered. Contains zero if a constant type of parameter is not 
entered. 


Pointer to the exponent: 

Contains a pointer to the string of digits in a floating-point 
numeric literal following the letter E, not including the sign if 
entered. 

Pointer to the decimal point: 

Contains a pointer to the decimal point in a fixed-point or 
floating-point numeric literal. If a decimal point is not entered, 
this field is zero. 
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STATEMENT NUMBER : Parse uses the IKJTERM macro to build a five word PDE 
to describe a STATEMENT NUMBER parameter. The PDE has the following 
format: 


+ 0 

T" 

1 

Lengthl | 

i 

+1 

T 

1 + 2 

Length2 | 

i 

Length3 

1 +3 

1 

x 

Reserved 

--j 

j 

+ 4 

Reserved 



T 

1 +6 

1 

l ... _ 

Flags 



-1 

j 

+ & 

A pointer 

to 

the 

program-id 




1 

+ 12 

A pointer 

to 

the 

line number 





+ 16 

A pointer 

to 

the 

verb number 




-j 


Lengthl 

Contains the length of the program-id specified but not including 
the following period. Contains zero if the program-id is not 
present. 


Length2 

Contains the length of the line number entered but not including 
the delimiting periods. Contains zero if the line number is not 
present. 


Length3 

contains the length of the verb number entered but not including 
the preceding period. Contains zero if the verb number is not 
present. 


Flags 

Byte 1 

0 ... .... 

1 . 

. 1 .. .... 

.. 1 . _ 

...1 .... 
.... xxxx 
Byte 2 

xxxx xxxx 


The parameter is missing. 
The parameter is present. 
Constant. 

Variable. 

Statement Number. 
Reserved. 

Reserved. 


Pointer to the program-id: 

Contains a pointer to the program-id, if entered. 
Contains zero if not present. 

Pointer to the line number: 

Contains a pointer to the line number, if entered. 
Contains zero if not present. 

Pointer to the verb number: 

Contains a pointer to the verb number, if entered. 
Contains zero if not present. 
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VARIABLE : Parse builds a five word PDE (when using the IKJTERM macro) 

to describe a VARIABLE parameter. The PDE has the following format: 


i- 1 

I + 0 I 

I A pointer to the data-name | 

|- T -t-t-*1 

|+4 |+5 |+6 |+7 | 

| Lengthl | Reserved | Flags | Reserved j 

i- 1 - a - x - 1 

I +8 | 

| A pointer to the PDE for the first qualifier. | 

I- 1 

I +12 | 

j A pointer to the program-id name. j 

l- T - T --- T --f 

| +16 j +17 | +18 | +19 j 

| | Number of | Number of | | 

| Length2 | Qualifiers j Subscripts | Reserved | 

l- x _ x - x _j 


Pointer to the data-name: 

Contains a pointer to the data-name. If a program-id qualifier 
precedes the data-name, this pointer points to the first character 
after the period of the program-id qualifier. 

Lengthl 

Contains the length of the data-name. 

Flags 

Byte 1 

0... .... The parameter is missing. 

1... The parameter is present. 

.1. Constant. 

..1. Variable. 

... 1 .... Statement Number. 

.... xxxx Reserved. 

Pointer to the PDE for the first qualifier: 

Contains a pointer to the PDE describing the first qualifier of the 
data-name, if any. 

This field contains X'FFOOOOOO* if no qualifiers are entered. 

Note : The format of the PDE for a data-name qualifier follows this 

description. 

Pointer to the program-id name: 

Contains a pointer to the program-id name, if entered. This field 
contains zero if the optional program-id name is not present. 

Length2 

Contains the length of the program-id name, if entered. Contains 
zero if the optional program-id name is not present. 

Number of Qualifiers 

Contains the number of qualifiers entered for this data-name. (For 
example: if data-name A of B is entered, this field would contain 

1 .) 

Number of Subscripts 

Contains the number of subscripts entered for this data-name. (For 
example: if data-name A(1,2) is entered this field would contain 

2 .) 
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The format of a DATA-NAME QUALIFIER is: 


1 +0 

1 

1_ 

A pointer 

to the data-name 

qualifier. 



1 — 

1 +1 * 

1 

L_ 

1 

Length j 

+5 

Reserved 

T 

1 +6 

| Flags 

— — 

+ 

1 i 

Reserved 

1 +8 


A pointer to the PDE for the next qualifier. 


Pointer to the data-name qualifier. 

Contains a pointer to the data-name qualifier. 


Length: 

Contains the length of the data-name qualifier. 


Flags 

xxxx xxxx Reserved 


Pointer to the PDE for the next qualifier: 

Contains a pointer to the PDE describing the next qualifier, if 
any. This field contains X'FFOOOOOO' for the last qualifier. 


RESERVED WORD : Parse uses the IKJRSVWD macro to build a two word PDE 
(using the IKJRSVWD macro instruction) to describe a RESERVED WORD 
parameter. The PDE has the following format: 

Note : This PDE is not used when the IKJRSVWD macro instruction is 

chained from an IKJTERM macro instruction. In this case, the 
reserved-word number is returned in the CONSTANT parameter PDE built by 
the IKJTERM macro instruction. 


r~ 

j +0 

Reserved 

T 

1 +2 

1 

i 

Re served-word 

number 

i +4 

L 

Reserved 

1 + 6 

1 

± 

“ “ * T 

1 +7 

Flags | 

-L 

Reserved 


Reserved-word number: 

The reserved-word number contains the number of the IKJNAME macro 
instruction that corresponds to the entered name. 


Note : The possible names of reserved words are given by coding a 

list of IKJNAME macros following an IKJRSVWD macro. One IKJNAME 
macro is needed for each possible name. If the name entered does 
not correspond to one of the names in the IKJNAME macro list then 
this field is set to zero. 


Flags 

Byte 1 

0 . 




•xxx xxxx 


The parameter is missing. 
The parameter is present. 
Reserved. 
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EXPRESSION : Parse uses the IKJOPER macro to build a two word PDE to 

describe an EXPRESSION parameter. The PDE has the following format: 


+0 


Reserved 


+4 


Reserved 


1*6 

I 

-X- 


♦7 


Flags | 


Reserved 


Flags 

Q« * . .... 

1. 

.XXX xxxx 


The entire parameter (expression) is missing. 
The entire parameter (expression) is present. 
Reserved. 


IKJIDENT PDE : Parse uses the IKJIDENT macro instruction to build a 
two-word PDE to describe a non-delimiter dependent positional parameter; 
it has the following format: 


f- 

I +0 
l 

,- 

I +4 

| Length 


- n 

I 

A pointer to the character string | 

- T - T - j 

|+6 |+7 | 

| Flags | Reserved | 

_ ± _JL- --J 


Pointer to the character string: 

Contains a pointer to the beginning of the character string. 
Contains zero if the character string is omitted. 


Length: 

Contains the length of the character string. 


Flags: 

0. 

1. 

| .XXX xxxx 


The parameter is not present. 
The parameter is present. 
Reserved bits. 


Affect of List and Range Options on PDE Formats 

The formats of the IKJPARMD mapping DSECT and of the PDEs built by the 
Parse service routine are affected by the options you specify in the 
Parse macro instructions, as well as by the type of parameter specified. 
If you specify the LIST or the RANGE options in the Parse macro 
instructions describing positional parameters, the IKJPARMD DSECT and 
the PDEs returned by the Parse service routine are modified to reflect 
these options. 

LIST : The LIST option may be used with the following positional 

parameter types: 

• USERID 

• DSNAME 

• DSTHING 

• ADDRESS 

• VALUE 

• CONSTANT 

• VARIABLE 

• STATEMENT NUMBER 

• Any non-delimiter dependent positional parameter. 
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If you specify the LIST option in the Parse macro instructions 
describing the above listed positional parameter types, the Parse 
service routine allocates an additional word for the PDE created to 
describe the positional parameter. This word is allocated even though a 
list may not actually be entered by the terminal user. If a list is not 
entered, this word is set to hexadecimal FF000000. If a list is 
entered, the additional word will be used to chain the PDEs created for 
each element found in the list. Each additional PDE has a format 
identical to the one described for that parameter type within the 
IKJPARMD DSECT• Since the number of elements in a list is variable, the 
number of PDEs created by the Parse service routine is also variable. 

The chain word of the PDE created for the last element of the list is 
set to hexadecimal FF000000. 

Figure 123 shows the PDL returned by the Parse service routine after 
three positional parameters have been entered. In this case, the first 
two parameters, a USERID and a STRING parameter, had been defined as not 
accepting lists. The third parameter, a VALUE parameter, had the LIST 
option coded in the IKJPOSIT macro instruction that defined the 
parameter syntax. The VALUE parameter was entered as a two element 



Figure 123. A PDL Showing PDEs Describing a List 
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RANGE : The RANGE option may be used with the following positional 

parameter types: 

• ADDRESS 

• VALUE 

I « CONSTANT 
• VARIABLE 
• STATEMENT NUMBER 

• Any non-delimiter dependent positional parameter. 

If you specify the RANGE option in the Parse macro instructions 
describing the above listed positional parameter types, the Parse 
service routine builds two identical, sequential PDEs within the PDL 
returned to the calling routine. Space is allocated for the second PDE 
even though a range may not actually be supplied by the terminal user. 

If a range is not supplied, the second PDE is set to zero. The flag bit 
which is normally set for a missing parameter will also be zero in the 
second PDE. 

Figure 124 shows the PDL returned by the Parse service routine after 
two positional parameters have been entered. In this case, the first 
parameter is a USERID parameter and the second parameter is a VALUE 
parameter that had the RANGE option coded in the IKJPOSIT macro 
instruction that defined the parameter syntax. For this example, the 
VALUE parameter was not entered as a range, and, consequently, the 
second PDE is set to zero. 


PDL - Mapped by IKJPARMD DSECT 

PDL Header 


USERID PDE 


VALUE PDE 

(May be entered as a Range) 

VALUE PDE built to receive second element of Range. 
(Parameter was not entered as a Range) 


Figure 124. A PDL Showing PDEs Describing a Range 
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COMBINING THE LIST AND RANGE OPTIONS : If you specify both the LIST and 
RANGE options in a Parse macro instruction describing a positional 
parameter, the Parse service routine builds two identical PDEs within 
the PDL returned to the calling routine. Both of these PDEs are 
formatted according to the type of positional parameter described. 

These two PDEs describe the RANGE. An additional word is appended to 
the second PDE for the purpose of chaining any additional PDEs built to 
describe the LIST. 

Figure 125 shows this general format. 



Figure 125. PDL Showing PDEs Describing LIST and RANGE Options 

If you have specified both the LIST and the RANGE options in the 
Parse macro instruction describing a positional parameter, the user at 
the terminal has the option of supplying a single parameter, a single 
range, a list of parameters, or a list of ranges. The construction of 
the PDL returned by the Parse service routine can reflect each of these 
conditions. 
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Figure 126 shows the PDL returned by the Parse service routine if the 
user enters a single parameter. 



Figure 126. PDL - LIST and RANGE Acceptable, Single Parameter Entered 

As Figure 126 shows, the second PDE and the chain word are both set 
to zero by the Parse service routine, if the LIST and RANGE options were 
coded in the macro instruction describing the parameter, but the user 
entered a single parameter. 


Figure 127 shows the PDL returned by the Parse service routine if the 
user enters a single range of the form: 

parameter :parameter 



Figure 127. PDL - LIST and RANGE Acceptable, Single Range Entered 

As Figure 127 shows, both PDEs are filled in to describe the single 
RANGE parameter entered by the user. The chain word is set to 
hexadecimal FF000000 to indicate that there are no elements chained onto 
this one; that is, the parmaeter was not entered in the form of a LIST. 
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Figure 128 shows the format of the PDL returned by the Parse service 
routine if the user enters a list of parameters in the form: 

(parameter, parameter,...) 



Figure 128. PDL - LIST and RANGE Acceptable, LIST Entered 

As Figure 128 shows, each of the first PDEs and the chain word 
pointers are filled in by the Parse service routine to describe the list 
of parameters entered by the user. The second, identical PDEs are 
zeroed to indicate that the parameter was not entered in the form of a 
range. 

The last set of PDEs on the chain will contain hexadecimal FF000000 
in the chain word to indicate that there are no more PDEs on that 
particular chain. 
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The PDL created by the Parse service routine to describe a parameter 
entered as a list of ranges is similar to the one created to describe a 
list. The difference is that the second, identical PDEs are also filled 
in by Parse to describe the ranges entered. 

Figure 129 shows the format of the PDL returned by the Parse service 
routine if the user enters a list of ranges in the form: 

(parameter parameter , parameter:parameter, ...) 



Figure 129. PDL - LIST and RANGE Acceptable, A LIST of Ranges Entered 
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As Figure 129 shows, each of the PDFs and each of the second, 
identical PDEs are filled in by the Parse service routine to describe 
the ranges entered. The chain words are also filled in to point down 
through the list of parameters entered. 

The last set of PDEs on the chain will contain hexadecimal FF000000 
in the chain* word to indicate that there are no more PDEs on that 
particular chain. 

The PDE Created for a Keyword Parameter 

Parse builds a halfword (2 byte) PDE to describe a KEYWORD parameter; it 
has the following format: 

+ 0 

r-1 

|Number | 

I + 2 | 

L_J 

Number: 

You describe the possible names for a KEYWORD parameter to the 
Parse service routine by coding a list of IKJNAME macro 
instructions directly following the IKJKEYWD macro instruction. 

One IKJNAME macro instruction must be executed for each possible 
name. 

The Parse service routine places the number of the IKJNAME macro 
instruction, that corresponds to the keyword name entered, into the 
PDE. 

If the keyword is not entered, and you did not specify a default in 
the IKJKEYWD macro instruction, the Parse service routine places a 
zero into the PDE. 


ADDITIONAL FACILITIES PROVIDED BY PARSE 

The Parse service routine, in addition to determining if command 
parameters are syntactically correct, provides the following services 
which may be selected by the calling routine. 

Translation to Upper Case 

Positional parameters are ordinarily translated to uppercase unless the 
calling routine specifies ASIS in the IKJPOSIT or IKJIDENT macro 
instructions. The first character of a value parameter, the 
type-character, is always translated to uppercase, however. The string 
that follows the type character is translated to uppercase, unless ASIS 
is coded in the describing macro instructions. 

Parse always translates keyword parameters to upper case. 

Insertion of Default Values 


Positional parameters (except delimiter and space) and keyword 
parameters may have default values. These default values are indicated 
to the Parse service routine through the DEFAULT= operand of the 
IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD, IKJIDENT, and IKJKEYWD macro 
instructions. When a positional or a keyword parameter is omitted, for 
which a default value has been specified. Parse inserts the default 
value. Parse also inserts the default value you specified if a 
parameter is invalid and the terminal user enters a null line in 
response to a prompt. 
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Passing Control to a Validity Checking Routine 


You can provide a validity checking routine to do additional checking on 
a positional parameter. Each positional parameter can have a unique 
validity checking routine. Indicate the presence of a validity checking 
routine by coding the entry point address of the routine as the VALIDCK= 
| operand in the IKJPOSIT, IKJTERM, IKJOPER or IKJIDENT macro 
instructions. 

Parse can call validity checking routines for the following types of 
positional parameters: 

• STRING 

• VALUE 

• ADDRESS 

• QSTRING 

• USERID 

• DSNAME 

• DSTHING 

• CONSTANT 

• VARIABLE 

• STATEMENT NUMBER 

• EXPRESSION 

• And any non-delimiter dependent parameters. 

The validity check exit is taken after the Parse service routine has 
determined that the parameter is syntactically correct. If a DSNAME or 
USERID parameter is entered with a password. Parse takes the validity 
check exit after first parsing both the userid or dsname and the 
password. If the terminal user enters a list, the validity check 
routine is called as each element in the list is parsed. If a range is 
entered. Parse calls the validity check routine only after both items of 
the range are parsed. 

When control is passed from Parse to a validity checking routine. 
Parse uses standard linkage conventions. The validity check routine 
must save Parse's registers and restore them before returning control to 
Parse. The Parse service routine builds a three word parameter list and 
places the address of this list into register 1 before branching to a 
validity checking routine. This three-word parameter list has the 
format shown in Figure 130. 


Number of 
Bytes 


Field 


j Contents or Meaning 


H 


PDEADR |The address of the Parameter Descriptor Entry 

|(PDE) built by parse for this syntactically 
|correct parameter. 




USERWORD [The address of the user work area. This is 
|the same address you supplied to the Parse 
|Service routine in the Parse Parameter List. 


— ^ 

VALMSG |Initialized to HEX FF000000 by PARSE. A user 

|provided validity checking routine can place 
|the address of a second level message in this 
j field. 

L-X_X- 

Figure 130. Format of the Validity Check Parameter List 
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Your validity checking routines must return a code in general 
register 15 to the Parse service routine. These codes inform Parse of 
the results of the validity check and determine the action that Parse 
should take. Figure 131 shows the return codes, their meaning, and the 
action taken by the Parse service routine. 


j Return Code j 

I*- 


Meaning 


Action Taken by Parse | 

-H 


|The parameter is valid. 

i 

I 


|No additional processing is 
jperformed on this parameter by 
|the Parse service routine. 




|The parameter is invalid.jParse writes an error message 
| jto the terminal and prompts 

| |for a valid parameter. 


| The parameter is invalid.(The validity checking routine 
| |has issued an error message; 

| jParse prompts for a valid 


I 


j parameter. 


- j. --|-----] 

12 | The parameter is invalid;|Parse stops all further syntax| 

|the processor cannot jchecking and returns to the 

(continue. (calling routine. 

L-X-X_ 

Figure 131. Return Codes from a Validity Checking Routine 


If Parse receives a return code of 4 or 8, the new data entered in 
response to the prompt is parsed as if it were the original data and 
control is again passed to the validity check routine. This cycle 
continues until a valid parameter is obtained. 


Insertion of Keywords 


Some keyword parameters may imply other keyword parameters. You may 
specify that other keywords are to be inserted into the parameter string 
when a certain keyword is entered. Use the INSERT operand of the 
IKJNAME macro instruction to indicate that a keyword or a list of 
keywords is to be inserted following the named keyword. The inserted 
keywords are processed as if they were entered from the terminal. 

Issuing Second Level Messages 

You may supply second-level messages to be chained to any prompt message 
issued for a positional parameter - (keyword parameters are never 
required). Use the HELP operand of the IKJPOSIT, IKJTERM, IKJOPER, 
IKJRSVWD or IKJIDENT macro instructions to supply these second level 
messages to the Parse service routine. You can supply up to 255 
second-level messages for each positional parameter. One second-level 
message is issued each time a question mark is entered from the 
terminal. If a question mark is entered and no second-level messages 
were provided, or they have all been issued in response to previous 
question marks, the terminal user is notified that no help is available. 

If a user provided validity checking routine returns the address of a 
second-level message to the Parse service routine, that second-level 
message or chain will be written out in response to question marks 
entered from the terminal. The original second-level chain, if one was 
present, is deleted. 
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Prompting 


The Parse service routine prompts the terminal user if the command 
parameters found are incorrect or if required parameters are missing. 

It allows the terminal user to enter a missing parameter or correct an 
incorrect one without having to reenter the entire command. Parse 
prompts, and the terminal user must respond, in the following 
situations: 

1. A userid or dsname was entered with a slash but without a password. 

2. A parameter is syntactically invalid. 

3. A keyword is ambiguous, that is, it is not clear to the Parse 
service routine which keyword of several similar ones is being 
entered. 

4. A required positional parameter is missing. The requirement for a 
particular positional parameter and the prompting message to be 
issued if that parameter is not present, are specified to the Parse 
service routine through the PROMPT operand of the IKJPOSIT, 

IKJTERM, IKJOPER, IKJRSVWD, and IKJIDENT macro instructions. Parse 
puts out the prompting message supplied in the macro instruction. 

5. A validity check exit indicates that a parameter is invalid. 

There are a number of rules that govern the processing of responses 
entered from the terminal after a prompt. 

1. All of the new data entered is parsed before the scan of the 
original command is resumed. 

2. Unless otherwise stated in the command syntax definition, the new 
parameter is entered as it is entered in the original command. See 
the section on Command Parameter Syntax for exceptions to this 
rule. 

3. In general, additional parameters may be entered along with the 
data prompted for. It must be kept in mind, however, that all of 
the new data entered is parsed before the scan of the material in 
the original command buffer is resumed. A problem could occur in a 
situation where a command is entered followed by two positional 
parameters and a keyword, and the first positional parameter is 
invalid. Parse issues a prompt for the first positional parameter. 
When the user at the terminal reenters that first positional 
parameter, it would be invalid to enter additional keywords along 
with it. The additional keywords would be scanned before the 
second positional parameter and an error condition would result 
when parse returned to the original command buffer and found a 
positional parameter. 

Keep in mind also, that if the parameter prompted for is within a 
subfield, only parameters valid within that subfield may be entered 
along with the parameter prompted for. 

4. In general, a null response is acceptable only for optional 
parameters. However, if a null response is entered for an optional 
parameter that has a default. Parse inserts the default. If a 
prompt for a required parameter is answered by a null response from 
the terminal. Parse reissues the prompt message. Parse continues 
prompting until a correct parameter is entered. The terminal user 
can request termination by entering an attention. 
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Parse will always accept a null response to a prompt for a 
password, whether or not the dsname or userid parameters are 
required. It is the responsibility of the routine using the Parse 
service routine to insure that the correct password was entered if 
one was required, by checking the password pointed to by the PDE 
returned by Parse. 

5. If a required parameter which may be entered in the form of a list 
is missing, or if it was entered as a single parameter (not as a 
list), and that single parameter is incorrect. Parse will not 
accept a list after the prompt. The user at the terminal must 
enter a single parameter. 

If however, the item was entered as a list but an item within the 
list is invalid. Parse accepts one or more parameters after the 
prompt. Parse considers these newly entered parameters to be part 
of the original list. No parameters not valid in the list may be 
entered from the terminal in response to this prompt. 

If the last item in a list is found to be invalid. Parse only 
accepts one parameter after a prompt. 

6. If Parse determines that a parameter is invalid, the invalid 
portion of the parameter is indicated in the error message. The 
remainder of the parameter is not yet parsed. The user must 
reenter as much of the invalid parameter as was indicated in the 
error message. This situation often occurs if a dsname parameter 
or userid parameter is entered with blanks between the dsname or 
userid and the password. The dsname or userid may be invalid but 
the password is still good and will be parsed after a new dsname or 
userid is entered in response to the prompt. 

Parse always attempts to obtain syntactically correct parameters 
before returning to the calling routine. However, this is not always 
possible. The terminal user may have requested that no prompt messages 
be sent to the terminal, or the command being parsed may have come from 
a procedure. In these cases, an error message is issued and a code is 
returned to the calling routine indicating that a correct command could 
not be obtained. Any second level messages that would ordinarily be 
appended to the request for new data are appended to the error message. 
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EXAMPLES OF USING THE PARSE SERVICE ROUTINE 

EXAMPLE 1 

This example shows how the Parse macro instructions could be used within 
a Command processor to describe the syntax of an EDIT command to the 
Parse service routine. 

The EDIT command we are describing to Parse has the following format: 


EDIT 



BLOCK(number) 


LINE(number) 
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Figure 132 shows the sequence of Parse macro instructions that would 
describe the syntax of this EDIT command to the Parse service routine. 
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Figure 132. Coding Example 1 — Using Parse Macros to Describe Command 
Parameter Syntax 

The Parse macro instructions shown in Figure 132, when executed, 
perform two distinct functions. 

1. They build the Parameter Control List describing the syntax of the 
EDIT command parameters. The PCL is used by the Parse service 
routine during its scan of the parameters within the command 
buffer. 

2. They create the IKJPARMD DSECT (defaulted to on the IKJPARM macro 
instruction) that you use to map the Parameter Descriptor List 
returned by the Parse service routine after it scans the parameters 
within the command buffer. 

I Your code never refers to the PCL; it is used only by the Parse 
service routine. Therefore, it is not shown in the example. 
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Figure 133 shows the IKJPARMD DSECT created by the expansion of the 
Parse macro instructions. 
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Figure 133. An IKJPARMD DSECT (Example 1) 

If a terminal user entered the above described EDIT command in the 
form: 


EDIT SYSFILE/X PL1(3) NONUM BLOCK cr 

the Parse service routine would prompt for the blocksize as follows: 

"ENTER BLOCKSIZE" 

The user at the terminal might respond with: 

160 

The Parse service routine would then complete the scan of the command 
parameters, build a Parameter Descriptor List (PDL) f place the address 
of the PDL into the fullword pointed to by the fifth word of the Parse 
Parameter List, and return to the calling program. 

The calling routine uses the address of the PDL as a base address for 
the IKJPARMD DSECT. 

Figure 134 shows the PDL returned by the Parse service routine. The 
symbolic addresses within the IKJPARMD DSECT are shown to the left of 
the PDL at the points within the PDL to which they apply, and the 
meanings of the fields within the PDL are explained to the right of the 
PDL. 
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| Figure 134. The IKJPARMD DSECT and the PDL (Example 1) 
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EXAMPLE 2 


This example shows how the Parse macro instructions could be used to 
describe the syntax of a sample AT command that has the following 
syntax: 


i-r- 

j COMMAND I OPERANDS 

^- + - 

| | L stmt 

| AT | J(stmt-1 f stmt-2, 

| | (stmt-3:stmt-4 

l _x_ 


| (cmd r chain) COUNT(integer) 
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j 


The following figure shows the sequence of Parse macro instructions 
that describe this sample AT command to the Parse service routine. 
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Figure 135. Coding Example 2 — Using Parse Macros to Describe 
Parameter Syntax 

The Parse macro instructions shown in Figure 135, when executed 
perform two distinct functions. 

1. They build the Parameter Control List describing the syntax of the 
command parameters. This PCL is then used by the Parse service 
routine during its scan of the parameters in the command buffer. 

2. They create the IKJPARMD DSECT that you use to map the Parameter 
Descriptor List. The PDL is returned by Parse after it scans the 
parameters in the command buffer. 

Note: Your code never refers to the PCL; it is used only by the Parse 

service routine. Therefore* the Parameter Control List is not shown in 
the example. 
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Figure 136 shows the IKJPARMD DSECT created by the expansion of the 
Parse macro instructions. 
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Figure 136. An IKJPARMD DSECT (Example 2) 

In this example, if the terminal user entered the above described 
command incorrectly like this: 

AT 200/3 (list all) COUNT(a) 

the Parse routine would prompt the terminal user with the message: 

INVALID STATEMENT NUMBER, 200/3 

REENTER 

The user might respond with: 

200.3 

the Parse routine would then prompt the user with: 

INVALID COUNT, a 

REENTER 

The user might respond with: 

3 

This sequence resulted in the syntactically correct command of: 

AT 200.3 (list all) COUNT(3) 

The Parse routine would then build a Parameter Descriptor List (PDL) 
and place the address of the PDL into the fullword pointed to by the 
fifth word of the Parse Parameter List. 

Parse then returns to the caller and the caller uses the address of 
the PDL as a base address for the IKJPARMD DSECT. 
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Figure 137 shows the PDL returned by the Parse routine* The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields 
within the PDL is shown on the right. 
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I PDL Header, used only by 
| IKJRLSA 

Lengths (program-id, line no. 
and verb no.) 

Parameter is present 
No program - id 
Line number 
Verb number 

Double PDE for RANGE option, 
but not entered 

J 

LIST option not entered 
First character after ) 

Length, parameter is present 

First keyword 

Subfield 

Length, parameter is present 


PARS EAT 


STMTPCE 


POSITPCE 

KEYPCE 

IDENTPCE 


X'90 1 


Pointer to 200 


Pointer to 3 


X'00' 


X'FFOOOOOO' 


Pointer to LIST in string 


X'80 1 


Pointer to 3 


X'80' 


Figure 137. The IKJPARMD DSECT and the PDL (Example 2) 
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EXAMPLE 3 


This example shows how the Parse macro instructions could be used to 
describe the syntax of a sample LIST command that has the following 
syntax: 

r - T --- 

| COMMAND I OPERANDS 

|--j-- 

| LIST | symbol PRINT(symbol) 

l _x- 

The following figure shows the sequence of Parse macro instructions 
that describe this sample LIST command to the Parse service routine. 
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Figure 138. Coding Example 3 ~ Using Parse Macros to Describe 
Parameter Syntax 

The Parse macro instructions shown in Figure 138, when executed 
perform two distinct functions. 

1. They build the Parameter Control List describing the syntax of the 
command parameters. This PCL is then used by the Parse service 
routine during its scan of the parameters in the command buffer. 

2. They create the IKJPARMD DSECT that you use to map the Parameter 
Descriptor List. The PDL is returned by Parse after it scans the 
parameters in the command buffer. 

Note : Your code never references the PCL; it is used only by the Parse 

service routine. Therefore, the Parameter Control List for the example 
is not shown. 
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Figure 139 shows the IKJPARMD DSECT created by the expansion of the 
Parse macro instructions• 



Figure 139, An IKJPARMD DSECT (Example 3) 


In this example, if the terminal user entered the above described 
command incorrectly like this: 


LIST a of 1 in 3(1) PRINT(d) 


the Parse routine would prompt the terminal user with: 


INVALID SYMBOL, a...l in 3(1) 
REENTER 


The user might respond: 
a of b in 3(1) 

the Parse routine would then prompt with: 

INVALID SYMBOL, a...3(1) 

REENTER 


The user might respond with: 
a of b in c (1) 

This sequence resulted in the syntactically correct command of: 

LIST a of b in c(l) PRINT(d) 

The Parse routine would then build a Parameter Descriptor List (PDL) 
and place the address of the PDL into the fullword pointed to by the 
fifth word of the Parse Parameter List. 

Parse then returns to the caller and the caller uses the address of 
the PDL as a base address for the IKJPARMD DSECT. 

Figure 140 shows the PDL returned by the Parse routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields 
within the PDL is shown on the right. 
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IKJPARMD 
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PDL 

Description of 

Field Contents 







*Note: May not be contiguous in storage at this point. 


| Figure 140. The IKJPARMD DSECT and the PDL (Example 3) 
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EXAMPLE 4 


This example shows how the Parse macro instructions could be used to 
describe the syntax of a sample WHEN command that has the following 
syntax: 


COMMAND 

"T“ 

1 

-4-- 

OPERANDS 


WHEN 

T 

1, 

( addr 1 

(subcommand chain) 


1 

- JL - 

(expression/ 



The following figure shows the sequence of Parse macro instructions 
that describe this sample WHEN command to the Parse service routine. 


e 

X 

£ 

* 

4 





i 

K 

J 

p 

A 

R 

M 





P 

s 

0 

c 

0 

= 

p 


3 

s 

e 



— 




n 






















— 

Pj 

p 

n 

Q 

r 






1 

X 

J 

0 

P 

E 

R 





r 

e 

n 

X 

p_ 

r 

r 

e 

5 

s 

/ 

0 

n 

i 

t 

0 

/» 

E 



& 

1 

- 

S 

1_ 

m 

b 

0 

7 

i 

> 
































& 

P\ 

T 

R 

N 

0 

2 

= 

5 

y 

hr) 

b 

o 

i 

2 

* 

R 

5 

V 

IV 

D 

= 

O 

P 

e 


a 

i 

O 

















L n 















C 

H 

A 

I 

A/ 


a 

J 

<T 

r 

1 


P 

R 

0 

M 


7 

* 

f 

4 

e 

r 

m 

i 

> 

V 

A 

A 

J 

D 

c 

j? 


C 


e 

c 

7 


5 

X 

m 

b 

O 

/ 

1 




K 

7 

J 

1 

R 

M 





r 

s 

y 

m 

b 

O 

1 

i 

> 

> 

(/ 

P 

P 

E 

/? 



5 

f 

? 

J 

Y 

P 

E 

r 

y 

A 

R 

A 
































P 

R 

0 

M 

P 

7 

z\ 

r 

5 

Y] 

m 

6 

o 

1\ 

2 

> 

























0 

£j 

e 

n 


t 

0 

r 


i 

K 


R 

i 

V 

W 

D 




r 

O 

Pi 

* 

r 

a 


O 


i 

t 


* 

0 

M 

?_ 

7 

= 

f 

0 

P: 

« 

r 

<3 

% 

0 

r 

7 













1 









i 

K 

J 

H 

A 

M 

f 




— 

T 

e 

£ 

71 























- 



_ 


“1 






“1 



1 









i 

K 

J 

A/ 

I 

M 

£ 





f 

n 

e 

£. 

> 










1 

~1 







n 


















7 

y. 

m 

6 

0 

7} 

2} 



i 

K 

j 

7 

E 

R 

M 




J 

t 

s 

y 

m 

b_ 

o 

/ 

2 

t 

i 

7 

7 


I 



A 

i? 























a 

i_ 

d 

r 

I 





i 

K 

J 

J 

E 

R 

M 





r 

d 

d 

1 

r 

e 

5 

5^ 

T 


7 

K 

g 

E 

3 


A 

2 

t 

J 

j 

I 

I 

D 

C 

K 

7 

£| 

A 


c 

7 

7 








/ 

<L 


I 

0 

/7| 

e 



i 

K 

J 

P 

0 

5 

/ 

T 




l 

5 

I 

R 

h 

N 

G 

; 

i 

E 

i 

1 

i 

C 

3 

= 

f 

H 

£ 

C 

X 

2 






_ ] 














_ 


_ 






i 

K 

l 

E 

H 

D 

P 













— 



















] 

1 

n 










L_ 


Figure 141. Coding Example 4 — Using Parse Macros to Describe 
Parameter Syntax 

The Parse macro instructions shown in Figure 141, when executed 
perform two distinct functions. 

1- They build the Parameter Control List describing the syntax of the 
command parameters. This PCL is then used by the Parse service 
routine during its scan of the parameters in the command buffer. 

2. They create the IKJPARMD DSECT that you to map the Parameter 

Descriptor List. The PDL is returned by Parse after it scans the 
parameters in the command buffer. 

Note : Your code never references the PCL; it is used only by the Parse 

service routine. Therefore, the Parameter Control List for this example 
is not shown. 
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Figure 142 shows the IKJPARMD DSECT created by the expansion of the 
Parse macro instructions. 



Figure 142. An IKJPARMD DSECT (Example 4) 


In this example, if the terminal user entered the above described 
command incorrectly like this: 

WHEN (a) (LIST b) 

the Parse routine would prompt the terminal user with: 

ENTER OPERATOR 

The user might then respond: 
eq 

the Parse routine would then prompt with: 

INVALID EXPRESSION, (a eq) 

REENTER 

The user might respond then with: 

(a eq b) 

This sequence resulted in a syntactically correct command of: 

WHEN (a eq b) (LIST b) 

The Parse routine would then build a Parameter Descriptor List (PDL) 
and place the address of the PDL into the fullword pointed to by the 
fifth word of the Parse Parameter List. 

Parse then returns to the caller and the caller uses the address of 
the PDL as a base address for the IKJPARMD DSECT. 
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RETURN CODES FROM THE PARSE SERVICE ROUTINE 


When it returns to the program that invoked it* the Parse service 
routine provides one of the following return codes in general register 
15: 


CODE 

decimal 

0 

4 

8 

12 

16 

20 

24 


MEANING 


Parse completed successfully. 

The command parameters were incomplete and Parse was unable 
to prompt. 

Parse'did not complete. An attention interruption occurred 
during Parse processing. The communications ECB is posted. 
The Parse Parameter Block contains invalid information. 

Parse issued a GETMAIN and no space was available. 

A validity checking routine requested termination. 
Conflicting parameters were found on the IKJTERM, IKJOPER or 
IKJRSVWD macro instruction. 
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Testing a Newly Written Program -- The TEST Command 


The TEST command permits a user at a terminal to test an assembly 
language program, including a user written TMP, Command Processor, or 
applications program. 


You test a program by issuing the TEST command and the various TEST 
subcommands that perform the following basic functions: 

• Execute the program under test from its starting address or from any 
address within the program. The GO, CALL, or RUN subcommand does 
this. An example is GO ERRTN which starts the program being tested 
at symbolic location ERRTN. 

• Display selected areas of the program as it currently appears in 
main storage, or display the contents of any of the registers. The 
LIST subcommand does this. An example is LIST 4R, which displays 
the contents of general register four. 

• Interrupt the program under test at a specified location or 
locations. Once you have interrupted the program you can display 
areas of the program or any of the registers, or you can issue other 
subcommands of TEST to be executed before returning control to the 
program under test. You can specify the subcommands you want 
executed at any of these break points by issuing the AT subcommand 
before execution of the program. In this case the subcommands named 
on the AT subcommand are executed automatically without your having 
to enter them when the program is interrupted. 

• Change the contents of specified program locations in main storage 
or the contents of specific registers. You do this with the TEST 
"assignment" function. An example is ERRTN=X*18D1*. This places 
the hexadecimal value 18D1 at symbolic location ERRTN. 

In addition to these basic debugging functions, the TEST command 
processor provides other facilities. Examples are the listing of data 
extent blocks (DEBs), data control blocks (DCBs), task control blocks 
(TCBs), program status words (PSWs), and providing a main storage map of 
the program being tested. A complete list of the TEST subcommands and a 
short description of their functions is provided in Figure 144* 
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Subcommand Name 


Function 


= (Assignment) 


AT 


CALL 


-+ 


Assigns values to one or more locations. 


Establishes breakpoints at specified locations. 


Initiates execution of a program at a specified 
address. 


COPY 


Moves data fields or addresses. 


—I 


DELETE 


DROP 


Deletes a load module. 


Removes symbolic addresses from the symbol table. 


END 

EQUATE 


Terminates all functions of the TEST command. 


Adds symbolic address to the symbol table. 


FREEMAIN 


Frees a specified number of bytes of main storage. 




GETMAIN 


Acquires a specified number of bytes of main storage 
for use by the program being processed. 




GO 


Restarts a program at the point of interruption or 
at a specified address. 


LIST 


Displays the contents of specified areas of main 
storage or the contents of specified registers. 


LISTDCB 


Lists the contents of a Data Control Block (DCB)• 
You must specify the address of the DCB. 


LISTDEB 


Lists the contents of a Data Extent Block (DEB). 
You must specify the address of the DEB. 


LISTMAP 


Displays a storage map of any storage assigned to a 
program. 


LI ST PS W 


LISTTCB 


Displays the Program Status Word (PSW). You may 
specify the address of any PSW. 


Lists the contents of the Task Control Block (TCB)• 
You may specify the address of any TCB. 


LOAD 


Loads a program into main storage for execution. 


-H 


OFF 


Removes breakpoints. 


QUALIFY 


Establishes the starting or base location for 
symbolic or relative addresses; resolves external 
symbols within load modules. 


RUN 


Voids all breakpoints so that a program can execute 
to termination. 


WHERE 


Displays the absolute address of a symbol or 
entrypoint, and its relative location within the 
CSECT. 


Figure 144. The TEST Subcommands 
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WHEN YOU WOULD USE TEST 


There are two basic situations in which you might want to use the TEST 
command: 

1. You want to TEST a program currently active in the system. 

2. You want to TEST a program not currently being executed. 

You may want to TEST a currently executing program either because it 
has begun to abnormally terminate, or because you want to check through 
the current environment to see that the program is executing properly. 

If a program has begun to abnormally terminate, you receive a 
diagnostic message from the Terminal Monitor Program and then a READY 
message. The TMP is in effect asking, "Do you want to terminate your 
program or test it?" If you respond with anything but TEST, your 
program is abnormally terminated by the ABEND routine. If, however, you 
issue the TEST command (no program name should be supplied), the TEST 
command processor is given control, and you can use the TEST subcommands 
to debug the defective program. 

If you just want to look at the current environment of an executing 
program that is not terminating abnormally, enter an attention. The 
currently active program is not detached and the TMP responds to your 
interruption by issuing its usual READY message. Issue the TEST command 
(no program name) and the currently active program remains in storage 
under the control of the TEST command processor. You can then use the 
TEST subcommands to investigate the current storage situation. 

Note that in the case of both the ABEND or the attention 
interruption, you do not enter a program name following the TEST 
command. If you enter the TEST command followed by the name of the 
currently active program, you lose the current in-storage copy of the 
program and TEST loads a new copy. 

The second use of the TEST command processor, testing a program not 
currently being executed, requires that you enter a program name along 
with the TEST command. When the Terminal Monitor Program issues a READY 
message to request a command, enter the command, TEST program name. 

(There are other optional operands of the TEST command but they are not 
necessary for this example.) The TEST command processor is given 
control and it loads a copy of the named program. The program can be a 
newly written TMP, CP, or applications program. 

Programs to be tested in this manner must be linkage edited members 
of partitioned data sets, or object modules in sequential or partitioned 
data sets, loadable by the Operating System Loader. 

While the program is under the control of TEST, you can step through 
the program, investigate or alter the environment at any time, change 
instructions or register contents, force entry into various subroutines, 
and perform other debugging operations online and immediately. 

It is this second use of the TEST command processor, especially the 
debugging of newly written code, that this section discusses. 

This section is not intended to be a complete discussion of the TEST 
command processor. For additional discussion of the TEST command and 
its operands, see TSO Command Language Reference and Terminal User 1 s 
Guide. 
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ADDRESSING RESTRICTIONS 


The TEST command processor can resolve internal and external symbolic 
addresses only if these addresses are available and can be obtained by 
TEST. Within certain limitations, symbolic addresses are available for 
both object modules (processed by the OS Loader) and load modules 
(fetched by Contents Supervision). To ensure availability of symbols, 
use the EQUATE subcommand of TEST to define the symbols you intend to 
use. 

External symbols, such as CSECT names, can be available for both 
object modules and load modules. Object modules require that the OS 
Loader had enough main storage to build in-core CESD entries. Load 
modules must have been processed by the Linkage Editor with the TEST 
parameter specified, or must have been fetched to main storage by the 
TEST command or its LOAD subcommand. 

Internal symbols are available only for load modules. You can refer 
to most internal symbols in load modules if you specified the TEST 
parameter during both assembly and link editing. Certain internal 
symbols, however, are not available. These include the names on EQU, 
DSECT, LTORG, and ORG assembler statements, and the symbolic names 
contained in system routines that operate in zero protection key. 

Symbolic addresses normally cannot be obtained for modules fetched 
from data sets which have been concatenated to SYS1.LINKLIB by use of a 
link library list in a member of SYSl-PARMLIB. If, however, these 
modules are brought into main storage by the TEST command processor 
(with the LOAD subcommand, or as an operand on the TEST command), then 
the symbolic addresses within these modules are available to TEST. 

If the necessary conditions for symbol processing are not met, you 
can use absolute, relative, or register addressing, but you cannot refer 
to symbols, unless you have previously defined them with the EQUATE 
subcommand of TEST. 


EXECUTING A PROGRAM UNDER THE CONTROL OF TEST 

Any program, if it is a linkage edited member of a partitioned data set 
or an object module in a sequential or partitioned data set, can be 
executed under the control of the TEST command processor. 

Issue the command TEST followed by the program name and those 
operands of the TEST command that either define the program or are 
necessary to its operation. These operands may consist of parameters 
necessary to the operation of the program under test, the keyword LOAD 
or OBJECT depending upon whether the program is a load or an object 
module, and the keyword CP or NOCP depending upon whether the program to 
be tested is a command processor or not. 

Any parameters that you specify in the TEST command are passed to the 
named program as a standard operating system parameter list; that is, 
when the program under test receives control, register one contains a 
pointer to a list of addresses that point to the parameters. 

If the program to be tested is a command processor, include the 
keyword CP (the default is NOCP). The test routine creates a Command 
Processor Parameter List, and places its address into register 1 before 
loading the program. 
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Figure 145 shows the sequence of operations leading up to and 
following the issuance of the TEST command. 


TMP 


TEST 


MYPROG 



Figure 145. Issuing the TEST Command 

1. The Terminal Monitor Program issues a READY message to the terminal 
to indicate that the user should enter a command. 

2. The user at the terminal answers with the command: 

TEST MYPROG CP 

3. The TMP uses the Command Scan service routine to determine that a 
valid command has been entered f and links to the TEST command 
processor. 

4. The TEST command processor, using the PARSE service routine, 
determines that the user wants a Command Processor Parameter List 
built and passed to the load module (LOAD is the default) MYPROG. 
TEST builds the CPPL, places its address into register one, and 
attaches the TEST loader which XCTLs to MYPROG. 

5. The TEST command processor informs the user at the terminal that it 
is ready to accept subcommands. TEST does this by writing the 
message TEST at the terminal. 

From this point on, the user can use any of the facilities provided 
by the TEST subcommands to test his program. 
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ESTABLISHING AND REMOVING BREAKPOINTS WITHIN A PROGRAM: 


Use the AT subcommand to establish breakpoints within the program being 
tested. Then issue the GO subcommand to begin execution of the program. 
To begin executing a newly loaded program, merely enter the subcommand 
GO - no address is required. When the breakpoints are encountered, as 
the program is being executed, processing is temporarily halted, and the 
message, AT address, is written to the terminal. You can then examine 
the executing program, its registers, and data areas to see that it has 
been executing properly. 

There are two methods of accomplishing this. 

1. You can specify a list of subcommands when you issue the AT 
subcommand. When a breakpoint is encountered, the TEST command 
processor issues each of the specified subcommands as if it had 
been entered from the terminal at that time. The subcommands 
execute and display the results of their execution at the terminal. 
If you specify GO as the last subcommand, control is automatically 
returned to the program under TEST at the point of interruption. 

If you do not specify GO as the last subcommand in the list, 
control is returned to you, at the terminal, after the last 
subcommand is executed. If you determine from the information 
displayed by the subcommands, that your program has executed 
properly up to that breakpoint, issue the GO subcommand. Your 
program resumes execution at the point of interruption and 
continues execution until another breakpoint, or the end of the 
program, is reached. 

2. If you do not specify a list of subcommands when you issue the AT 
subcommand, the TEST command processors returns control to you at 
the terminal each time a breakpoint is encountered. You can then 
check on your program's execution by entering the TEST subcommands 
directly from the terminal. 

Issue the OFF subcommand with no address operand to remove all 
breakpoints previously established. Issue the OFF subcommand followed 
by an address, a list of addresses, or a range of addresses to remove a 
single breakpoint, several breakpoints, or all breakpoints occurring 
within the range of addresses. 


DISPLAYING SELECTED AREAS OF STORAGE 

Use the various LIST subcommands to display the contents of a specified 
area of main storage, registers, or various control blocks at your 
terminal, or to write this information to a data set. There are six 
variations of the LIST subcommand; they are: 

1. LIST 

2. LISTMAP 

3. LISTTCB 

4. LISTDEB 

5. LISTDCB 

6. LISTPSW 

LIST : Use the LIST subcommand to display areas of storage or the 
contents of registers. The address required as an operand of the LIST 
subcommand can be one address, a list of addresses, or a range of 
addresses. The address may be specified as a symbolic address if a 
symbol table exists and contains the requested symbolic address. If no 
symbol table exists (the program was not linkage edited or did not save 
a symbol table), you can use the EQUATE subcommand to create a symbolic 
address for any location within the program, or you can specify the 
address as a relative address, an absolute address, or as a register 
containing an address. 
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If you use the LIST subcommand to list information found at an 
address specified by a symbol contained in a symbol table, the 
information is displayed in the character type and the length specified 
in the symbol table. You can, however, override the attributes 
contained in the symbol table by including attribute operands on the 
LIST subcommand. 

Use the LIST subcommand at any point during the execution of your 
program (use AT or an ATTENTION to stop the execution of the program), 
to determine whether data areas and registers contain proper data. If 
the data displayed is not what it should be, use the TEST subcommands to 
determine why the data is not as expected, or to modify the data in 
storage and continue execution of the program. 

LISTMAP : Use the LISTMAP subcommand to display at your terminal a map 

of all storage assigned to the program under test. Some of the 
information displayed after issuance of the LISTMAP subcommand is: 

• Region size. 

• Task Control Block address. 

* Program name, length, and location in storage. 

* Active Request Blocks, RB types, and the names of the programs 
associated with each of the RBs• 

LISTTCB s Use the LISTTCB subcommand to display the entire Task Control 
Block of the program under test, or any fields of that TCB. The 
information displayed is formatted, and each field is identified 
according to the field names contained in the publication System Control 
Blocks . 

If you want to display the TCB for the Program under test, enter the 
subcommand LISTTCB with no address. If you want to display another TCB 
on the TCB queue, you must include the address of the TCB as an operand 
of the LISTTCB subcommand. 

LISTDEB s Use the LISTDEB subcommand to display the Basic section and 
any direct access sections of any valid Data Extent Block (DEB), or any 
fields of that DEB. The information displayed is formatted according to 
the field names of the Data Extent Block as contained in the System 
Control Blocks publication. 

The LISTDEB subcommand requires the address of a DEB as an operand. 

LISTDCB : Use the LISTDCB subcommand to display the contents of a Data 

Control Block (DCB). The information displayed is formatted, and each 
field is identified according to the field names contained in the System 
Control Blocks publication. 

The LISTDCB subcommand requires the address of a DCB as an operand. 

If you have created the DCB within the program under test, use the 
address of the DCB macro instruction used to create the DCB. You can 
also obtain the address of the DCB from the DEBDCBAD field of the DEB 
displayed with the LISTDEB subcommand. 

LISTPSW s Use the LISTPSW subcommand to display the current Program 
Status Word or any of the PSWs at your terminal. If you issue the 
subcommand LISTPSW with no address following the subcommand, the current 
PSW is displayed at your terminal. If you want to display any of the 
other PSWs at your terminal, supply the address of the PSW you want to 
see as an operand of the LISTPSW subcommand. A list of the permanent 
in-storage locations of all PSWs can be found in the Principles of 
Operation publication. 

The PSW is displayed formatted by field, i.e. , system mask, key, 

AMWP, interruption code, ILD, CC, program mask, and instruction address. 
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CHANGING INSTRUCTIONS, DATA AREAS, OR REGISTER CONTENTS 

Once you have listed those areas of storage that help you determine just 
what has occurred in your program, you can use the assignment function 
of the TEST command to make corrections within the in-storage copy of 
the code, or to change the contents of data areas or registers. 

Simply enter the address at which you want the new data entered, a 
code indicating the data type, and the new data you want entered at that 
address. The address must conform to the address restrictions already 
discussed. The new data must be contained within single quotes. The 
data type codes can be found in the publication TSQ Command Language 
Reference . 

One problem that can arise during a debugging session occurs when you 
want to replace a section of the program under test but the replacement 
code is longer than the section to be replaced. If you merely type in 
the beginning address of the section to be replaced, followed by a 
portion of code longer than the segment to be replaced, you will overlay 
some functional code. You can solve this problem with the GETMAIN 
subcommand of TEST. 

Issue the TEST subcommand GETMAIN to obtain a work area in which to 
build your replacement segment of code. The GETMAIN subcommand writes 
out the address of the beginning of the storage area it obtained for 
you. Use the Assignment Subcommand of the TEST command to place a 
branch to the new area at the address in your module that begins the 
code you want to replace. Use the Assignment or COPY Subcommand to 
build your code segment in the newly obtained area. As the last 
instruction in your newly written code, place a branch back to the point 
within your module at which you want processing to resume. You can then 
use the GO subcommand to restart your program at some point before the 
branch. Your program will execute through the branch instruction and 
into the newly written code. If the new code works, you will execute 
the new instructions and branch back into your original code. Later, 
you can use the LIST subcommand to display the newly written code in a 
form useful to you, enter it into your program with the TSO EDIT 
command, and reassemble your now executable module. 


FORCING EXECUTION OF PROGRAM SUBROUTINES 

Certain paths through some programs are difficult to test because the 
combination of events leading to that path is difficult to produce. 

One example of this problem is processing after return codes. Your 
module might respond differently according to the codes returned to it 
by some other module or some other, not yet written, section of code. 
You can use the AT subcommand to insert a breakpoint in your program at 
the point where it passes control to the not yet existing code; the 
assignment function of TEST to set register 15 to the desired return 
code; and the GO subcommand to begin execution of your program at the 
point where control would have been returned. Using this sequence of 
TEST subcommands, you can test your module's response to each possible 
return code. 
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USING TEST AFTER A PROGRAM ABEND 


If a program running under TSO begins to ABEND* a diagnostic message 
containing the ABEND code is written to the terminal* ABEND processing 
is halted* and control is returned to either the TMP or TEST. If the 
program was running under the control of the TEST command processor* 
control is returned to TEST and you can immediately begin to use the 
TEST subcommands to determine the cause of the error. If the program 
was not running under TEST* control is returned to the Terminal Monitor 
Program. You can then enter the command TEST (no program name should be 
entered)* to place the abnormally terminating program under control of 
the TEST command processor. 

Use the ABEND code to determine the type of interruption that 
occurred. Issue the WHERE subcommand to determine where the 
interruption occurred. 

The WHERE subcommand is especially helpful. If you enter the WHERE 
subcommand* the current instruction address is displayed at the 
terminal. If you then enter WHERE followed by that instruction address* 
WHERE responds by printing out the program name, the CSECT name, the 
offset of the current instruction address within the CSECT* and the 
address of the abnormally terminating task's TCB. 

The instruction address* and the information returned by the WHERE 
subcommand pinpoint the point of error. 

Use the LIST subcommand to display the instructions leading up to the 
error condition* and to display data areas and registers used in those 
instructions. This information should be sufficient to determine the 
cause of the error. 

Determining Data Set Information 

If you want to investigate the condition of any of your data sets* 
perform the following operations: 

1. Use the LISTTCB subcommand to display the TCB for the terminating 
task. 

2. Use the contents of the TCBDEB field as an operand of the LISTDEB 
subcommand to gain access to the Data Extent Block queue. 

3. Use the contents of the DEBDCBAD field in each of the DEBs in the 
DEB queue* or the addresses of any DCB macro instructions coded 
within your program* as an operand of the LISTDCB macro 
instruction, to list the Data Control Blocks. 

These control blocks contain the addresses of other control blocks 
useful in the debugging process. See System Control Blocks publication. 
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Appendix A: TSO Control Blocks 


This appendix contains those control blocks frequently referenced by a 
programmer writing a Terminal Monitor Program or a command processor. 
They are: 

1. The Environment Control Table (EOT) 

2. The Protected Step Control Block (PSCB) 

3. The Time Sharing Job Block (TJB) 

4. The User Profile Table (UPT) 

These control blocks are shown exactly as they appear in the System 
Control Blocks publication. 

For each field the following information is provided: Offset, bytes 
and alignment, field name and field description. 

The "offset" column contains the decimal and hexadecimal displacement 
of the beginning of the field from the start of the data area. 

"Bytes and alignment" indicate the length of the field in bytes and 
the position of the beginning of the field based on a fullword boundary 
For example, . . 6 indicates that the field is six bytes in length and 
the field begins on the third byte of a fullword. 

If the field is composed of bits, each bit in a byte is shown in the 
"bytes and alignment" column. For example, 

. . 1 


1 ... .... 

. 1 .. 1 .,.. 

..XX .XXX 

indicates that the third byte of a fullword is composed of significant 
bit settings. The "field description" defines the bits when they are 
set as indicated. Bits indicated by an "x" are reserved for future use. 

When no settings are indicated (.), the field has the definition 

provided in "field description" only when the byte is equal to zero. 

The name of the field or bit is found in the "field name" column, and 
the meaning of the field is found in the "field description" column. 
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Environment Control Table 


The environment control table (ECT) is a 32-byte data area constructed by the 
Terminal Monitor Program (TMP). It contains information about the user's 
environment in the foreground region. This data area resides in subpool 1 and is 
updated by the command processors. It is used by the command processors and the 
TMP. Its address is in the CPPL. 


Offset 
Dec Hex 


Bytes and 
Alignment 


Field Name 


Field Description 


9 

12 

20 

28 


29 

32 

36 


ECTRCDF 


9 

C 

14 

1C 


.xxx xxxx 
. 3 

4 

1 


.XXX xxxx 

. 3 

8 


ID 

20 

24 


8 


1 ... _ 

.X.. ..XX 


8 

4 


ECTRTCD 

ECTIOWA 
ECT MS GF 


ECTSMSG 

ECTPCMD 

ECTSCMD 

ECTSWS 

ECTNOPD 

ECTATRM 

ECTLOGF 

ECTNMAL 

ECTNNOT 

ECTDDNUM 

ECTUSER 

none 


Indicates that the command processor has abnormally 
terminated. 

(Reserved bits) 

The return code from the last command processor, li 
ECTRCDF is set, this field contains the ABEND code. 

Address of the I/O work area. 


Indicates that the second level messages are to be 
deleted. 

(Reserved bits) 

The address of the second level message chain. 

Name of- the last primary command entered correctly 
by the terminal user. 

Name of the last subcommand entered correctly by the 
terminal user. 

Switches 

No operands exist in the command buffer. 

The command processor is being terminated by the 
Terminal Monitor Program. 

The Logon/Logoff command processor has requested the 
Terminal Monitor Program to log the user off. 

No user messages (MAIL) to be received at logon. 

No broadcast notices (NOTICES) at logon. 

(Reserved bits) 

Counter for temporary DDNAMES• 

Reserved for installation use. 

Reserved. 

_JL- 

Table 


Figure 146. Environment Control 
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Protected Step Control Block 


The Protected Step Control Block (PSCB) contains accounting information related to 
a single user. All timing information is in software timer units. A software 
timer unit is equal to 26.04166 micro seconds. Both the CPPL and the job step 
control block (JSCB), offset 264., point to the PSCB. (See System Control Blocks 
for further information on the JSCB.) 


Offset 
Dec Hex 


Bytes and 
Alignment 


Field Name 
PSCBUSER 

PSCBUSRL 

PSCBGPNM 


Field Description 


16 


24 


28 


32 


36 


10 


...X xxxx 


17 

11 

i 

i • i 

i 

18 

12 

1 

| . . 2 
i 

20 

14 

1 

1 4 

1 


18 

1C 

20 

24 


4 

4 


PSCBATRl 

PSCB CTRL 
PSCBACCT 
PSCBJCL 


Byte 2 

PSCBATR2 

PSCBCPU 

PSCBSWP 

PSCBLTIM 

PSCBTCPU 

PSCBTSWP 


Contains the user ID left aligned and followed by 
blanks if necessary. 

The length of the non-blank portion of the user ID. 

Group name is initialized by Logon with information 
from the User Attribute Data Set (UADS). Used by 
DAIR to obtain the default unit name, if invoker of 
DAIR does not specify unit name. (See DA08UNIT, 
DA24UNIT, and DA30UNIT fields in DAIR parameter 
blocks.) 

IBM user attributes. 

OPERATOR command user. 

ACCOUNT command user. 

SUBMIT, STATUS, CANCEL, OUTPUT command user. 
(Reserved bits) 

Reserved for IBM use. 

Available for use by the installation. 

The cumulative time used by this terminal user 
during this session. This field is set to zero 
during logon. 

The cumulative time that this terminal user has been 
resident in the region. This field is set to zero 
during logon. 

The actual time of day that this user logged onto 
the time sharing system for this session. 

The total CPU time used by this terminal user, 
excluding the current session. 

The total time that the terminal user has been 
resident in the region during this accounting 
period, excluding the current session. 


Figure 147. Protected Step Control Block (Part 1 of 2) 
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Figure 147. Protected step Control Block (Part 2 of 2) 
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Time-Sharing Job Block 


The Time Sharing Job Block (TJB) contains information about a time sharing job's 
status• This information must be retained in storage while a user is swapped out. 
TJBs are obtained during time sharing initialization and reside in the time 
sharing control task region. The address of a TJB table, containing the TJBs, is 
located at offset zero in the time sharing CVT. The time sharing CVT's address is 
stored at location 229 (E5) in the system CVT. 

Status information about terminals is contained in the Terminal Status Block 
(TSB). The address of the Terminal Status Block is the first word of the TJB. 

See TSQ Control Program PLM , for a description of the Terminal Status Block (TSB). 


Offset 
Dec Hex 


Bytes and 
Alignment 


. . 1 

1 ... .... 

... 1 .... 

. . ... . 1 . . 




Field Name 

+- 

TJBTSB 


TJBATTN 

TJBSTAX 

TJBSTAT 

TJBNJB 

TJBINCOR 

TJBLOGON 

TJBIWAIT 
TJBOWAIT 
TJBSILF 


TJBDISC 

TJBSILF2 


Field Description 


The address of the Terminal Status Block (TSB) that 
owns this terminal job. If this byte is zero, this 
job was started by operator command. 

The number of unprocessed attentions for this job. 

The number of scheduled STAX exits. 

First byte of status flags. 

This TJB is currently unused by TS0. 

This user is currently swapped in. 

Set by terminal input/output control (TIOC) at 
dial-up to request logon. 

Terminal job is in input wait state. 

Terminal job is in output wait state. 

Indicates that the user is to be logged off. Set by 
IKJSILF subroutine. Indicates that the region 
control task should invoke IKJEAT07 to either post 
with a 1 622* ABEND an out-of-storage job, or cancel 
the current job. 

Set by Logon/Logoff to request TIOC to disconnect 
line. 

System-initiated logoff is in progress. 


Figure 148. Time-Sharing Job Block (Part 1 of 3) 
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Offset 
Dec Hex 


Bytes and 
Alignment 


Field Name 


Field Description 


• 1 . t .. < 

.. 1 . .. 


Byte 1 


.XXX xxxx 


Byte 2 


. 1 .. _ 


.... .l.i 


TJBSTAT2 

TJBHUNG 

TJBHOLD 

TJBOCAB 

TJBRNAV 


TJBSURSV 

TJBQUIS 

TJBUSERR 

TJBDEAD 


TJBEXTNT 


TJBRCB 


TJBUMSM 


TJBSDCB 


TJBUTTMQ 


TJBUTTMP 


TJBRSTOR 


TJBOWP 

TJBIWP 

TJBLOGP 

TJBLWAIT 


TJBDDRD 

TJBFAT 

TJBDDRND 


TJBUMSMN 


Second byte of status flags* 

User*s communication line is disconnected without 
logging off. 

User is in an output wait due to a hold option. 

TSO failure resulting in an out-of-main-storage 
abnormal termination. 

The user cannot be logged onto TSO because of a 
machine check in region or the lack of a large 
enough region. 

Do not mark the swap unit available for use on next 
swap-in. 

Quiesce functions have started for the user. 

User is ready to run. 

Used by IKJEAT07 to indicate abnormal termination 
recursion. 

Address of the TJB extension. 

Address of the region control block for this job. 

Address of the user main storage map for this job. 

Address of the swap DCB for this user. 

Offset in TT map to first track map queue entry for 
the swap data set. 


Parallel swap. 

These bits along with byte 2 contain the offset into 
the map queue. The map queue contains a chain of 
allocation units for this user on the swap data set. 
The address of the queue is in the ROBUTTMQ field of 
the time sharing region control block. 


(See explanation of byte 1.) 

Restore flags. Tested by the Region Control Task 
(RCT) restore operation (IKJEAR03). 

Set by Terminal Input/Output Coordinator (TIOC) to 
end an output wait condition. 

Set by TIOC to end an input wait condition. 

Post the ECB that the logon image is waiting for. 
Set by time sharing control logon and by IKJSIIF. 
This user is in a long wait condition. If user is 
not made ready by restore processing f swap the user 
out again. 

Reset DDR non-dispatchability flag in TCB whose 
address is in IORMSCOM. 

An attention exit has been requested for the user. 
Set DDR non-dispatchability flag in TCB whose 
address is in IORMSCOM. 

Reserved bit. 

The number of map entries in the User Main Storage 
Map (UMSM). 
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Offset 


Dec 

Hex j 

Alignment 

i 

-I- 

Field Name 

28 

1C 

T 

1 

1 

8 

T 

1 

1 

TJBUSER 

36 

24 

1 

1 

4 

1 

l 

TJBIPPB 


Bytes and 


Field Description 


40 


28 


TJBNEWID 


41 

29 

i 

i • i 
i 

1 

| TJBFLUSL 

1 

42 

2A 

i 

| . . 2 

1 

1 

| TJBTJID 

I 

44 

2C 

1 

1 1 

1 

1 

| TJBMONI 

I 


45 2D 


...1 .... 

.... ..XX 

. 1 

1 . 

.... . 1 *. 


TJ3MDSN 


TJBMJBN 


TJBMSES 


TJBMSPA 


TJBMSTA 


TJBGETBF 


TJBSTAT3 

TJBDISC2 

TJBSOEM 


The ID of the user owning this job. 
trailing blanks. NOPURGE option. 


Padded with 


47 


2F 


The address of the first in a chain of 
Inter-Partition Post Blocks (IPPBs) indicating ECBs 
to be posted by the Restore routine. 

The region ID of the region into which this user 
should be logged on. When this field is set by the 
end-of-task routine for Logon/Logoff, it identifies 
the new region to which the user will be shifted. 

The field is zero if the region is selected by the 
Driver. 

Level of last STAX macro instruction that was issued 
with the NOPURGE option. 

The terminal job ID for this job. 

Flags indicating information requested. Set by the 
MONITOR subcommand of the OPERATOR command. Used by 
job management. 

Indicates that the first non-temporary data set 
allocated to a new volume should be displayed on 
this user's terminal as part of the MOUNT message. 
(Dsnames requested.) 

Indicates that the name of each job is to be 
displayed on this user's terminal when each job is 
initiated and terminated, and that the unit record 
allocations are to be displayed when a job step is 
initiated. (Jobnames requested.) 

Indicates that when a terminal session is initiated 
or terminated, a message is displayed on this user's 
terminal. (Session requested.) 

Indicates that the available space on a direct 
access device is to be displayed on this user's 
terminal as part of the DEMOUNT message. (Space 
requested.) 

Indicates that at the end of a job or job step 
certain data set disposition information should be 
printed with the DEMOUNT messages. These 
dispositions are: KEEP, CATLG, or UNCATLG. (Status 
requested.) 

TPUT should try to obtain additional buffers for the 
user before entering a wait condition. 

(Reserved bits) 


Disconnect this TJB. 

Indicates swapout error message recursion. 
Reserved 
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User Profile Table 


The User Profile Table (UPT) is a 16-byte data area located in subpool zero. The 
UPT contains information about the terminal user and is created by the 
LOGON/LOGOFF Scheduler from information stored in the user attribute data set and 
from parameters of the LOGON command. It is updated by the PROFILE command 
processor. The UPT address is in the CPPL. 


r t — — 

| Offset | Bytes and 
j Dec Hex| Alignment 

-T* 

1 

1 

_ 1. 

’ - — T - - ~ - — -*“-1 

1 1 

Field Name | Field Description | 

i j 

r 

0 

0 

T 

1 2 

1 

T 

1 

i 


T 1 

| Reserved for IBM use. 

i 

2 

2 

| . . 10 
i 

1 

1 

i 

UPTUSER 

1 

|Reserved for installation use. 

i 

12 

C 

1 

1 1 

1 

1 

1 

| 

UPTSWS 

1 

(User environment switches. 

i 



1 

| .0. 

1 

1 

! 

i 

UPTNPRM 

1 

jPrompting is to be done. 

I 



1 

1 

1 

i 

i 


1 

|No prompting. 

1 



1 

J..0. •«.. 

1 

l 

i 

i 

UPTMID 

1 

|Message identifiers suppressed. 

i 



1 

1 

1 

1 

i 


1 

|Message identifiers printed. 

I 



1 

J...0 .... 

1 

1 

1 

i 

UPTNCOM 

1 

(Allow user communication via SEND command. 

i 



1 

1 ...1 .... 

1 

1 

1 

i 


1 

|No user communication. 

i 



1 

j..«. 0 e e s 

1 

1 

1 

I 

1 

i 

UP TP A US 

1 

jNo prompting pause for B ? s when in non-interactive 
(mode (i.e. f when next input is not from terminal). 

i 



1 

1 

i 

1 

i 


1 

(Prompting pause for •?■ when in interactive mode. 

i 



1 

!.... .0*. 
i 

1 

1 

i 

UPTALD 

1 

(ATTENTION is not a line delete character. 

i 



1 

i 

i 

1 

1 

1 

i 


1 

(ATTENTION has been specified as a line delete 
j character. 

i 



1 

|X... ..XX 

1 

1 

i 


1 

(Reserved bits. 

i 

13 

D 

1 

1 • 1 

1 

1 

i 

i 

UPTCDEL 

1 

(Character deletion character . ± 

14 

E 

1 

1 . . 1 

1 

1 

i 

UPTLDEL 

1 

|Line deletion character. A 

i 

15 

F 

1 

1 ... 1 
-X 

1 

i 


1 

| Reserved. 

x .. .. ... ..... .. ... 1 

| ^See 

System Control Blocks for 

1 

further information. | 


L-J 

Figure 149. User Profile Table 
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Appendix B: Notation for Defining Macro Instructions 


The notation used in this publication is described in the following 
paragraphs - 


1. The set of symbols listed below are used to define macro 

instructions, but should never be written in the actual macro 
instruction. 

hyphen 

underscore __ 

braces {} 

brackets [] 

ellipsis ... 

The special uses of these symbols are explained in paragraphs 5-9. 


2. Upper-case letters and words, numbers, and the set of symbols 
listed below should be written in macro instruction exactly as 
shown in the definition. 

apostrophe * 

asterisk * 

comma , 

equal sign = 

parentheses () 

period 


3. Lower-case letters, words, and symbols appearing in a macro 
instruction definition represent variables for which specific 
information should be substituted in the actual macro instruction. 

Example : If name appears in a macro instruction definition, a 

specific value (for example, ALPHA) should be substituted for the 
variable in the actual macro instruction. 


4. 


Braces group related items, such as alternatives. 
Example : The representation 


ALPHA=( 



D) 


indicates that a choice should be made among the items enclosed 
within the braces. If A is selected, the result is ALPHA=(A,D). 
If B is selected, the result can be either ALPHA=(,D) or 
ALPHA=(B,D). 
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5. Brackets also group related items; however, everything within the 
brackets is optional and may be omitted. 

Example : The representation 


ALPHA=( 



indicates that a choice can be made among the items enclosed within 
the brackets or that the items within the brackets can be omitted. 
If B is selected, the result is: ALPH A= (B,D) • If no choice is 
made, the result is: ALPHA=(,D). 


6. Stacked items represent alternatives. Only one such alternative 
should be selected. 


Example : The representation 

V| (a) 

HI ° r ic B | 


indicates that either A or B or C should be selected. 


7. Hyphens join lower-case letters, words, and symbols to form a 
single variable. 

Example : If member-name appears in a macro instruction definition, 

a specific value (for example, BETA) should be substituted for the 
variable in the actual macro instruction. 


8. An underscore indicates a default option. If an underscored 

alternative is selected, it need not be wirtten in the actual macro 
instruction. 


Example: 


The representation 



indicates that either A or B or C should be selected; however, if B 
is selected, it need not be written, because it is the default 
option. 


An ellipsis indicates that the preceding item or group of items can 
be repeated more than once in succession. 

Example: 


ALPHA[,BETA]... 


indicates that ALPHA can appear alone or can be followed by ,BETA 
any number of times in succession. 
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Glossary 


The following are definitions of words 
and phrases which are used in this 
publication but are not defined in IBM Data 
Processing Glossary, GC20-1699. For words 
and phrases which are in general use in 
IBM publications, refer to IBM Data 
Processing Glossary . 

in-storage list ; A chain of input lines in 
main storage, such as commands in an EXEC 
procedure, that are used in place of 
terminal input. 

Logical line : One or more lines typed at a 
terminal and treated as a unit. A logical 


line may consist of one or more physical 
lines, in which the symbol"indicates 
continuation. 

LOGOFF : The TSO command that terminates a 

user's terminal session. 

LOGON : The TSO command that a user must 

enter to initiate a terminal session. 

LOGON procedure ; A cataloged procedure 
that is executed as a result of a user 
entering the LOGON command. 

profile (user) ; The set of characteristics 
that describe the user to the system. 
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Index 


Indexes to systems reference library 
manuals are consolidated in the publication 
IBM System/360 Operating System: Systems 
Reference Library Master Index , Order 
No. GC28-6644• For additional information 
about any subject listed below, refer to 
other publications listed for the same 
subject in the Master Index. 


=(Assignment) subcommand of TEST 291,297 
ABEND 

completion code 39 
interception 25, 29, 39 
message to terminal 29 
options after an ABEND 27 
STAE, STAI relationships 25 
types of 25 
abnormal termination 
of subtasks 25 

of Terminal Monitor Program 25 
responding to 19 
abnormally terminating subcommand 
processors 39 

absolute address parameter, definition 213 
access time 35 
address parameter 

definitions 213-214 
expression 214 

forms of the address parameter 213-214 
in the command processor parameter list 
92 

of the format-only line 145 
of the GETLINE input buffer 118 
of the I/O service routine parameter 
block 93 

restrictions for TEST 293 
required in the Input Output Parameter 
List 92-103 
allocate 

data set by DDNAME 69 
data set by DSNAME 60 
data set to the terminal 68 
DDNAME to the terminal 68 
SYSOUT data set 74 
utility data set 60 
allocating 

data sets after LOGON 54 
during program execution 54 
Assignment(=) subcommand of TEST 291,297 
asterisk in place of positional 
parameter 219 

AT subcommand of TEST 291,295 
ATTACH macro instruction 24 
attention 

exit routines in a command processor 40 
interruption, definition of 19 
attention exit parameter list 32 


Attention Exit Handling routines 
address of 30 
more than one 30 

parameters received by 30-31,47-48 
registers at entry 30 
scheduling 19,47 
specifying 47 

Attribute control block (ATRCB) 76 


balanced parentheses (PSTRING) 215 
BLKSIZE in data control block 89 
BSAM, length of text line 89 
BSAM and QSAM macro instructions 8 6-88 
buffer input 118,166 
buffer size, TGET 178 
input to 87,88 

buffering, exchange and simple 89 
buffering techniques supported under TSO 
89 


chaining second level messages 146 
characters 

separator 212 

types recognized by Command Scan and 
Parse 206 

CHECK macro instruction 93 
checking 

syntax of command operands 208 
validity of command operands 271 
coding examples 

GETLINE macro instruction 120-121 
Parse macro instructions 285 
PUTGET macro instruction 169 
PUTLINE, single line data 133 
second level informational 
chaining 147-148 
text insertion 144-145 
STACK specifying an in-storage list as 
the input source 107-109 
STACK specifying the terminal as the 
input source 104 
STAX macro instruction 48-50 
TGET macro instruction 178 
TPUT macro instruction 174 
coding guidelines for command processors 
34 

combining the LIST and the RANGE options 
256-264 
command 

adding a 41 

inf ormation ,about (HELP) 41-43 
requesting a 23-24 
command library 

adding a new member or concatenating a 
new data set 41 
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command name 

determining validity of 201 
entered after ABEND 27 
syntactically valid 19,201 
command, obtaining 24 
command operand 

default values 270 
syntax checking 208 
validity checking 271 
command parameter syntax 211 
command procedure processing 102 
command processors 

ABEND return code 39 
adding to SYSl.CMDLIB 41 
allocating and freeing data 
sets 38,54 

attention exit routines 40 
basic functions of 18 
breaking into load modules 37 
coding guidelines 34 
completion code 39 
data set information 38,54-84 
definition of 34 
detaching 25 
error routines 37 

executing in TS link pack area 35 
intercepting ABENDS 39 
minimizing the amount of data 
swapped 37 
module size 37 
parameter list (CPPL) 92 
program design 35 
reducing storage requirements 36 
requests for subcommands 38 
relationship to the rest of TSO 34 
reset input stack after an attention 
interruption 40 
response time 35 
storage requirements 37 
using the TSO service routines 37 
validity checking exits 39 
writing your own 34 
command processor parameter list 
(CPPL) 92 
Command Scan 

control blocks 203 
flags passed to 204 
operation of 205 
output area 205 
results of 207 
service routine 19,202 
entry point 201 
return codes 207 

used by the Terminal Monitor Program 33 
Command Scan and Parse Service 
routines 201 

character types recognized 206 
sequence of operations 201 
command scan output area (CSOA) 205 
command scan output area and command buffer 
settings 207 

command scan parameter list (CSPL) 204 
command name syntax for user-written 
commands 202 

command syntax defining 222 
communicating with the user at the 
terminal 18-19 


concatenating 

command libraries 41 
data sets 63 
DDNAMES 63 
HELP data sets 41 
| constant parameter type 212,216 
control blocks 

displaying 20,295-296 
passed between the Terminal Monitor 
Program and command processors 91-92 
passed to the I/O service routines 
92-94 

required by Command Scan service 
routine 203 

required by Dynamic Allocation Interface 
Routine (DAIR) 55 
required by PUTGET service routine 
164,168 

used by GETLINE service routine 119 
control flags in the GETLINE parameter 
block 117 

conversational messages (PUTGET) 149 
COPY subcommand of TEST 231,237 
CP or NOCP (operand of TEST) 293 
current source of input 96 

DAIR (Dynamic Allocation Interface 
routine) 20,54 

control blocks 55 

definition 54 

entry codes 57 

entry point 55 

functions provided by 54 

IKJDAIR entry point 55 

IKJEFD00 load module 55 

indicating requested function to 58 

link to 55 

return codes 76-84 

used by Terminal Monitor Program 25 
DAIR parameter blocks 58-78 
DAIR parameter list (DAPL) 56 
data control block merge 34 
data definition (DD) statement 20,89 
for batch processing and TSO 89 
in LOGON PROC 20 
modifying for TSO 89 
data lines, definition 133 
data name 217 
data name qualifier 217 
data set 

allocation 54 
allocation by DDNAME 69 
allocation by DSNAME 60 
allocation to the terminal 68 
concatenating 63 
deconcatenating 65 
freeing 66-67 
marking allocatable 38,73 
marking not in use 73 
name, finding 57,59 
processing 54 
qualifiers 65 
SYSOUT, allocation of 74 
used during TSO session 22 
utility, allocation of 55 
data set extension (DSE) 
duplicate entries in 63 
search for data set name 58-59 
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data set name, searching for 58-59 
data swapped, amount of 35 
DCB merge 34 
DD DYNAMS 20 
DDNAME, allocation by 69 
DD statements (see data definition 
statement) 

deconcatenating data sets 64 
DEFER operand of STAX macro 48-49 
Defining command syntax 222 
delete 

elements from the input stack 96,99 
macro instruction 95 
procedure element from the input 
stack 99 

second level messages 38,46 
delimiter, definition 213 
delimiter dependent parameters 211,224 
detaching a command processor 25 
determine data set information with the 
TEST command 298 
determining the validity of 
commands 201 

device type for swap data sets 37 
diagnostic error message 39 
DSECT= 223 
DSNAME 

allocation by 60 
definition 215 
formats 215 
parameter missing 219 
DSTHING, definition 216 
dumping areas of a program 20,295-296 
dynamic allocation 20,54 
return codes 80-84 
Dynamic Allocation Interface routine 
(DAIR) 20,54 

return codes 76-84 


ECB, STOP/MODIFY 33 

ECT (environment control table) 39,300 
ECTMSGF bit, use of 46,146,165 
element, input stack 
adding 100 
code 102 
deleting 96,99 
end of file 87,88 
entry codes to DAIR 57 
entryname, syntax of 214 
environment control table (ECT) 39,300 
EODAD exit 87 
error messages 39 
establishing and removing TEST 
breakpoints 295 

event control block, STOP/MODIFY 33 
examples 

IKJPARMD DSECT 285-286 
message identifier stripping 
(PUTLINE) 141 

PDE formats effected by LIST and RANGE 
options 263,264 
PDL returned by Parse service 
routine 287 

text insertion (PUTLINE) 142 
using the Parse service routine 275 


exchange buffering 84 
EXEC statement of LOGON procedure 17 
execute form of I/O service routine macro 
definition of 90 

executing a command processor from the Time 
Sharing Link Pack Area 35 
executing a program under the control of 
TEST 20,293 
exit, EODAD 87 
| expression 218 
expression, address 214 
expression value, syntax of 214 
EXTRACT macro instruction 33 


I figurative constant 217 
finding data set name 58-59 
finding data set qualifiers 65 
I fixed-point numeric literal 216 
fixed record format 89 
flag field in TGET/TPUT parameter 
registers 181 

flags passed to Command Scan 204 
I floating-point numeric literal 216 
floating point register address, syntax of 
214 

forcing execution of program subroutines 
under TEST 297 
format-only function 145 
formatting the HELP data set 42-44 
formatting the output line 142 
forward chain pointers 136 
freeing 

a data set 66-67 
GETLINE buffers 38 
GETLINE input buffer 118 
PUTGET buffer 38,167 


gaining control after a TMP task ABEND 29 
general register address, syntax of 214 
GET macro instruction 87 
GETLINE macro instruction 
coding examples 120,121 
control blocks used by 119 
definition 18,111 
end of data processing 116 
execute form 103 
list form 111 

logical line processing 116 
operands 111,113 
return codes 122 

returned record, identifying source of 
116 

sources of input 116 
GETLINE buffer 123 
freeing 38 

get line parameter block (GTPB) 117 
initializing 111 

GETMAIN subcommand of TEST 291,297 
GTPB (the getline parameter block) 117 
GTSIZE macro instruction 185 

HELP data cards 43 
HELP data set 41-42 
formatting 42-44 
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identification (USERID), format of 215 
identifying the source of a record returned 
by GETLINE 116 
IKJCPPL DSECT 92 
IKJCSOA DSECT 205 
IKJCSPL DSECT 204 
IKJDAIR, entry point to 55 
IKJENDP macro instruction, format of 249 
IKJGTPB DSECT 117 

IKJIDENT macro instruction, format of 239 
IKJIOPL DSECT 93 

IKJKEYWD macro instruction, format of 244 
IKJLSD DSECT 105 

IKJNAME macro instruction, format of 
245,246 

I IKJOPER 210,232 
IKJPGPB DSECT 160-161 

IKiTPARM maoro instruction format of 223 
IKJPARMD DSECT 208,252 
example of 285,286 
IKJPARS entry point 201 

IKJPOSIT macro instruction, format of 224 
IKJPPL DSECT 251 
IKJPTGT load module 95 

IKJRLSA macro instruction, format of 249 
| IKJRSVWD 210,236 

IKJSCAN entry point 201 

IKJSUBF macro instruction, format of 248 
I IKJTERM 210,228 

Indirect address, definition and levels 
214 

information about commands (HELP) 41-44 
informational messages 45,138 
inhibit prompting 162 

initialization of the Terminal Monitor 
Program 23 
initializing 

getline parameter block 111 
input/output parameter block 90 
putget parameter block 150,160 
putline parameter block 131 
stack parameter block 101,102 
stax parameter list 51 
input buffer 118,166 
input line format 118,166 
input stack 96 

adding an element 100 
deleting elements 96,99 
input sources 46,100-101,165 
changing 96 
current 96 

input to the BSAM/QSAM macro 
instructions 87-88 
I/O macro, uses of 95 
Input wait after a prompt 166 
I/O parameter blocks, modifying 90 
I/O parameter list 92,93 

building with GETLINE macro 120 
initializing 90 
I/O service routines 90 

control blocks passed to 92-94 
entry points 95 

execute form macro, definition 90 
load module 95 
macro instructions 95 
parameter block, address of 93 
inserting default values into command 
operands 270 


inserting keywords into a parameter string 
272 

in-storage list as input source 100-103 
coding example 107-109 
in-storage list element, adding 96,100 
in-storage source data set 

adding an element to the input stack 
for 96,101 

instructions, changing 297 
intercepting ABENDS 25,29,39 
interrupting a program at a specified 
location 20,295 
invalid information in JFCB 34 
issuing second level prompting 
messages 272 


JFCB, invalid information in 34 
job control language (JCL) 89 
job file control block (JFCB) merge 
invalid information in 34 


keyword 

insertion 272 
parameters for Parse 221 
parameter descriptor entry (PDE) 270 
subfields 221,248 


length of text line processed by BSAM 89 
levels of indirect addressing 214 
line format, input 118,166 
line number, statement number parameter 
218 

LINK macro instruction 

to invoke I/O service routines 95 
to invoke IKJPARS 250 
to invoke TEST command processor 27 
list element, in-storage 

adding to input stack 96,100 
link pack area, time sharing 

executing a command processor in 34 
list forms of macro instructions, 
definition 90 

list source descriptor (LSD) 105 
listing the keyword parameter names 245 
LIST option of Parse 263,264 
LIST subcommand of TEST 295 
LISTDCB subcommand of TEST 296 
LISTDEB subcommand of TEST 296 
LISTMAP subcommand of TEST 296 
LISTPSW subcommand of TEST 296 
LISTTCB subcommand of TEST 296 
load modules 
IKJEFD00 55 
IKJPTGT 95 

loadname, syntax of 214 
locating data set name 58-59 
LOCATE mode of GET, PUT, PUTX macros 87-88 
logical line processing (GETLINE) 116 
logon catalogued procedure 22 
EXEC statement 17 
LOGON/LOGOFF Scheduler 22 
LRECL in DCB 89 

LSD (List Source Descriptor) 105 
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macro instruction, I/O 
definition 90 
macro notation 307 
main storage map 20 

marking data sets allocatable 38,73 

marking data sets not in use 73 

member name, syntax of 215 
merge, reverse 34 
messages 

building 142-145 
classes, definition 45 
conversationa1 149 

error 39 
formatting 90 
handling 45-46 
ID stripping 141 
identifier, definition 141 
levels 45 
line processing 138 

additional for PUTLINE 141 
lines 138 

mode (definition) 45,165 
multilevel 

definition 138,162 
writing 136 

passing to PUTGET service routine 162 
passing to PUTLINE service routine 139 
without message identifiers 
(restriction) 141,146 
meta language, definition 307 
methods of constructing an IOPL 92 
missing DSNAME 216 
missing operands 273 
missing positional parameters 211 
mode messages, definition 45,165 
move mode of GET, PUT, and PUTX macros 
87-88 

multilevel messages, definition 138,162 
multiline data 136 

multiple lines of output, BSAM/QSAM 89 

name, unqualified (definition) 215 
naming the PDL (DSECT=) 223 
no message identifiers on second level 
messages 141,146 
no output line (PTBYPS) 151 
NOCP or CP (operand of TEST) 293 
non-delimiter dependent positional 
parameters 216,239 
non-zero return code from Parse 249 
NOPAUSE processing of an in-storage 
list 46 

notation for defining macro 
instructions 307 

number of bytes moved by TGET (buffer 
size) 178 
null line entered 
after ABEND 27 

in response to a prompting message 270 
null PSTRING, definition 215 
null quoted string (QSTRING) 
definition 216 
null string, definition 213 

OLD (Output Line Descriptor) 123,139 
example of use 144-145 
OFF subcommand of TEST 291,295 
on-line testing 20,290 


operand 

descriptions (HELP) 41 
I in an expression 218 
missing 273 

| operator, expression parameter 218 
output line descriptor (OLD) 123,139 
example of use 144-145 
output line 

formats 133,162 
formatting 142 
output message 

building 142-145 
no response required 122 
response required 149 

with the PUTLINE macro instruction 122 
with the WRITE macro instruction 88 
OUTPUT=0 (keyword of PUTGET macro) 150 

parameter control entry (PCE) 222-249 
beginning the 223 

built by IKJENDP macro instruction 241 
built by IKJIDENT macro 
instruction 241-243 
built by IKJKEYWD macro 
instruction 224-225 
built by IKJNAME macro 
instruction 247 
I built by IKJOPER 234 

built by IKJPARM macro instruction 223 
built by IKJPOSIT macro 
instruction 226-227 
| built by IKJRSVWD 237 

built by IKJSUBF macro instruction 248 
J built by IKJTERM 230 

parameter control list (PCL) 222 
examples 285,286 
parameter descriptor entries 
(PDE) 222,252 

parameter descriptor list (PDL) 252 
beginning the 223 
parameters 

address, forms of 213-214 
passed to attention handling 
routines 30 

passed to command processors 25 
passed to the Test command processor 27 
positional (see positional parameters) 
parameter string, inserting keywords into 
272 

parenthesized string (PSTRING), format of 
215 

PARM field of LOGON EXEC statement 23 
Parse macro instructions 
coding examples 285 
combining LIST and RANGE options 
256-264 

LIST option 263,264 
order of coding for positional 
parameters 224,239 
RANGE option 220,265 
Parse parameter list, format of 251 
Parse Service routine (IKJPARS) 201 
character types recognized 206 
entry point 201 
examples of use 275 
keyword parameters 221 
macro instructions 222-249 
parameter descriptor list, example 286 
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Parse Service routine (IKJPARS) (continued) 
passing control to 250 
positional parameters 211 
prompting 267-268 

releasing storage allocated by Parse 
249 

responses 273 
return code 249 
scanning the input buffer 201 
types of command parameters recognized 
211 

using the service routine, 
examples 275 
passing control 

to commands and subcommands 19 
to command processors 23 
to I/O service routine 95 
to Parse service routine 250 
to TEST command processor 27 
to validity checking routine 271 
passing message lines 

to the PUTGET service routine 162 
to the PUTLINE service routine 139 
passing parameters to an attention exit 
47-4 8 

password 38,215 
PAUSE processing 46 
PDE (parameter descriptor entry) 
chain word 263,264 

effect of LIST and RANGE options on 
format 263,264 
types: 

ADDRESS parameter 255 
I CONSTANT 258 

DSNAME or a DSTHING parameter 254 
| EXPRESSION 263 

expression value parameter 257 
KEYWORD parameter 270 
non-delimiter dependent parameter 
263, 264 

positional parameter 252 

I reserved word 262 

statement number 260 
STRING, PSTRING, or a QSTRING 
parameter 253 
USERID parameter 258 
VALUE parameter 253 
| VARIABLE 261 

format (general) 252 

PDL 

header 252 
naming (DSECT=) 223 
perform a list of DAIR operations 72 
physical line processing 116 
pointer 

forward chain 136 
to the formatted line 145 

to the I/O service routine parameter 

block 93 

positional parameters 221 
asterisk in place of 219 
entered as lists or ranges 208,220,263 
missing 211 

order of coding Parse macros 224,239 
not dependent upon delimiters 219,239 
PPMODE 25 

primary text segment, offset of 142,143 
providing attention exits (STAX) 47 


processing modes 89,149 

processing a source in-storage list 46 

processing a STOP command 33 

Profile command 46,141,166 

program 

areas, displaying 20,295-296 
interruption at a specified location 
(TEST) 20,295 

program status word (PSW), displaying 
20,296 

primary text segments 142 
print inhibit (PTBYPS) 151,156 
private HELP data sets 42 
prompt message 

processing 166 
second level 272 
prompting 

for missing operands 273 
inhibiting 162 
input wait after 167 
messages 45 

the user at the terminal 273 
processing 

an attention interruption 30 
HELP data sets 41 
input 100-101 
program-id, 

statement number parameter 218 
variable parameter 217 
program execution, examining 295 
protected step control block (PSCB) 301 
PSTRING, syntax of 215 
PSW 

at time of abnormal termination 29 
displaying 20,295 

purging the second level message chain 146 
PUT macro instruction 85 
PUTGET buffer, freeing 38,166 
PUTGET parameter block 160-161 
initializing 150,160 
PUTGET macro instruction 
coding example 169 
format 150,155 
OUTPUT=0 150 

PUTGET service routine 149 
coding example 169-171 
control blocks 164,168 
input buffer 38,166 
input line format 166 
macro instruction, execute form 154 
macro instruction, list form 150 
message ID stripping 

(See PUTLINE message line processing) 

141 

mode message processing 165 
no output line 165 
operands 150,155 
output line 

preventing (PTBYPS) 151 
types and formats 162 
output line descriptor (OLD) 163 
PAUSE processing 46,156 
processing of second level messages 45 
providing the GET (ATTN) function only 
151 

question mark processing 165-166 
return codes 172 
sources of input 149 
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PUTGET service routine (continued) 
text insertion 162 
TGET options (TERMGET) 152,158 
TPUT options (TERMPUT) 151,156 
types of Output Line Descriptor 162 
PUTLINE functions for message lines 141 
PUTLINE macro instruction 
coding example 133 
format of 123 

PUTLINE parameter block 131-133 
initializing 130 
PUTLINE service routine 122 
coding examples of 144-145 
control flags 132 

macro instruction, execute form 126 
macro instruction, list form 123 
message line processing 141 
message processing control 
blocks 140 
operands 123,127 
processing of second level 
messages 45,138-139 
return codes 149 
text insertion 142 
TPUT (TERMPUT) options 124,128 
types and formats of output lines 133 
PUTX macro instruction 85 

QSTRING, definition 216 
| qualification, variable parameter 217 
qualified address, definition 214 
| qualifier, data name 217 
question mark 

entered after ABEND 27 
processing 90,165-166 
quoted string (SQSTRING) syntax of 216 


RANGE, use of (general) 220 
range option, how to use 265 
READ macro instruction 88 
reading a record from the terminal (the 
READ macro instruction) 88 
record formats 

supported under TSO 89 
undefined 89 

record returned by GETLINE 

identifying the source of 116 
reducing access time 35 
reducing swap time 35 
register contents 
changing 20,297 
when the TMP is attached 23 
relative address, syntax of 214 
| reserved word 218 
response time 35 
restrictions 

addressing for TEST 293 
for user-written TMP 22 
non-delimiter dependent parameters 219 
return codes 

Command Scan 207 
DAIR 76-84 

Dynamic Allocation 80 
GETLINE 122 
Parse 288 
PUTGET 172 
PUTLINE 149 


STACK 110 
STAX 53 
TGET 180 
TPUT 177 

validity checking routines 272 
reverse merge 34 
RTAUTOPT macro instruction 186 

SAM terminal routines 87 
second level messages 
deleting 38,46,146 
informational messages 146 
messages handled by Parse 272 
message chain 38,146-148,162 
no message identifiers 146 
requesting 45 

writing to the terminal 146 
separator characters 206,211 
sequence of operations, TEST 294 
Service routines, I/O (see I/O Service 
routines) 

simple buffering 89 
single level messages 138,162 
single line data 133 
source data set, in-storage 100-103 
adding an element to the input stack 
96,101 

source data set processing 101 
source, effects on message processing 46 
sources of input 100 
changing 96 
current 96 

space parameter, definition 216 
SPAUTOPT macro instruction 187 
special functions of the Terminal Monitor 
Program 33 

Stack input (see input stack) 

STACK macro instruction, format of 96,98 
stack parameter block (STPB) 101-102 
STACK service routine 96 

coding examples 104,107-109 
control block structures 
102-103,105-106 
element code 102 

macro instruction, execute form 98 
macro instruction, list form 96 
return codes 110 
STAE 

exit routines 39 

exit cannot correct problem 29 
macro instruction 19,29 
retry routines 39-40 
work area 29 

STAE/STAI exit routine guidelines 39-40 
STAI operand of ATTACH macro 39-40 
| statement number parameter 218 
STATTN macro instruction 188 
STATUS macro instruction 189 
STAUTOCP macro instruction 190 
STAUTOLN macro instruction 191 
STAX parameter list (STPL) 51 
STAX service routine 47 

coding example of STAX macro 
instruction 48-50 
DEFER operand 48-49 
macro instruction format 48-50 
passing parameters in registers 50 
return codes 53 
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STBREAK macro instruction 192 

STCC macro instruction 193 

STCLEAR macro instruction 195 

STCOM macro instruction 196 

string, definition 213 

stripping message identifiers 141 

STOP/MODIFY event control block (ECB) 33 

storage areas, displaying 295 

storage map 36 

storage requirements, reducing 36 
STSIZE macro instruction 197 
STTIME0U macro instruction 198 
subcommand name, syntactically valid 
19,201 

subcommand processors, abnormally 
terminating 39 

subfields associated with keyword 
parameters 245,246,248 
subfield descriptions 248 
| subscript, variable parameter 217 
substitute mode of PUT and PUTX macros 88 
subtask ABEND 25 
SVC 93 173 

swap data sets 37 
swap device type 37 
swap time 35,37 
reducing 35 
swapping 35 

symbolic address, definition 214 

for the parameter descriptor list 223 
for TEST 293 

syntax checking a command 202 
SYSABEND data set 29 

system catalog, searching for data set 
name 5 9 

system code ' 331 * 87, 88 

SYSOUT data set, allocation of 74 
SYSUDUMP data set 29 
SYS1•CMDLIB 41 

SYSl • HELP - the HELP data set 41 
SYS1.LINKLIB, data sets concatenated to 
293 


TCLEARQ macro instruction 199 
terminal, allocating a data set to 68 
terminal as input source 100,104 
terminal attention interruption element 
(TAIE) 32 

terminal, communicating with 18-19 
Terminal control macro instructions 185 
terminal element, adding to input stack 
96,100 

coding example 104 
terminal job identifier (TJID) 177 
terminal line size 89 
Terminal Monitor Program (TMP) 22-33 
control blocks passed to command 
processors 91-92 
definition 22 
fresh copy after ABEND 29 
functions of 18 
initialization 23 
intercepting an ABEND 25,29 
link to TEST command processor 27 
obtaining a command 25 
parameters passed to a command 
processor 25 


processing an attention interruption 30 
processing a STOP command 33 
shared subpool 23 

restriction on installation supplied 
TMP 22 

special functions of 33 
STAE exit 29 
STAI exit 25 
STOP/MODIFY ECB 33 
TIME function 33 
using Command Scan 33 
Terminal user's options after ABEND 29 
TERM=TS (operand of DD statement) 89 
TEST command processor 290 

addressing restrictions 293 
AT subcommand 295 
breakpoints, removing 295 
changing instructions, data areas, or 
register contents 297 
CP or NOCP operand 293 
definition 290 

determining data set information 298 
displaying selected areas of 
storage 295 

entering the command 285,292-293 
EQUATE subcommand 291,293 
examining a program not currently 
executing 293 

examining an executing program 297 
forcing execution of program 
subroutines 297 
GETMAIN subcommand 291,297 
list of subcommands 291 
LIST subcommand 295 
LISTDCB subcommand 296 
LISTDEB subcommand 296 
LISTMAP subcommand 296 
LISTPSW subcommand 296 
LISTTCB s ubcommand 2 96 
NOCP or CP operand 293 
OFF subcommand 291,295 
restrictions, addressing 293 
sequence of operations 294 
symbol processing 293 
testing a newly written program 290 
WHERE subcommand 291,298 
testing after a program ABEND 297 
TEST command 290 
test parameter list (TPL) 27-29 
testing, on-line 20,290 
TEST breakpoints, removing 295 
Text insertion 142,162 

coding examples 142,144-145 
TGET macro instruction 178 

coding examples 178,182,184 
definition 178 
format 178 

number of bytes moved 178 
register form 178 
return codes 180 
used by GET 87 
used by READ 88 
TGET/TPUT SVC 173 

macro instructions 174,178 
parameter registers 181 
TMP restriction 25 
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TPUT macro instruction, format of 174 
coding example 174,182 
definition 174 
register form 174 
return codes 177 
used by PUT and PUTX 88 
used by WRITE 88 
TIME function of the TMP 33 
time-sharing job block (TJB) 303 
time sharing link pack area 35 
TJB 303 

TJID (operand of TPUT) 177 
TJIDLOC (operand of TPUT) 177 
translating 

lower case letters to upper case 204 
positional parameters to upper case 
TSEVENT macro instruction 25 
TSO control blocks 299 
TSO I/O service routines 90 


TSO storage map 35-36 
UPT (user profile table) 306 
user, communicating with 18-19 
User LOGON PROC, example 22 
user profile table (UPT) 306 
userid, definition and format 215 
utility data set allocation 60 


value, definition 213 
validity check parameter list 271 
validity checking exits 39,271 
variable length record format 89 
variable parameter 217 
verb number 218 


WHERE (subcommand of TEST) 298 
WRITE macro instruction 88 
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